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

1

2

3

4

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

5

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

6

</description>

7

8

<description>This function is invoked by the importimport

9

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

10

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

11

semantics of the import statement. For examples of why

12

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

13

ihooksihooks and

14

rexecrexec. See also the built-in

15

module impimp, which defines some useful

16

operations out of which you can build your own

17

__import__() function.

18

For example, the statement import spam results in the

19

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

20

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

21

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

22

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

23

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

24

__import__() function does not set the local variable

25

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

26

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

27

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

28

globals only to determine the package context of the

29

import statement.)

30

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

31

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

32

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

33

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

34

name is returned. This is done for compatibility with the

35

bytecode generated for the different kinds of import statement; when

36

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

37

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

38

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

39

to find the eggs variable. As a workaround for this

40

behavior, use getattr() to extract the desired

41

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

42

def my_import(name):

43

mod = __import__(name)

44

components = name.split('.')

45

for comp in components[1:]:

46

mod = getattr(mod, comp)

47

return mod

48

</description>

49

<param name="name" optional="0">name</param><param name="globals" optional="1">globals</param><param name="locals" optional="1">locals</param><param name="fromlist" optional="1">fromlist</param>

50

<insert>__import__(name, [globals], [locals], [fromlist])</insert><dialog title="Insert __import__">__import__(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

51

52

53

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

54

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

55

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

56

57

58

59

60

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

61

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

62

an object is an instance of str or unicode.

63

isinstance(obj, basestring) is equivalent to

64

isinstance(obj, (str, unicode)).

65

New in version 2.3</description>

66

67

<insert>basestring()</insert><dialog title="Insert basestring">basestring()</dialog><info title="Info window"></info></function>

68

69

70

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

71

procedure. If x is false or omitted, this returns

72

False; otherwise it returns True.

73

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

74

Class bool cannot be subclassed further. Its only instances

75

are False and True.

76

New in version 2.2.1

77

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

78

79

80

81

82

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

83

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

84

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

85

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

86

class instances are callable if they have a __call__()

87

method.</description>

88

<param name="objectobject" optional="0">objectobject</param>

89

<insert>callable(objectobject)</insert><dialog title="Insert callable">callable(%0)</dialog><info title="Info window"></info></function>

90

91

92

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

93

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

94

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

95

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

96

if i is outside that range.</description>

97

98

99

100

101

<description>Return a class method for function.

102

A class method receives the class as implicit first argument,

103

just like an instance method receives the instance.

104

To declare a class method, use this idiom:

105

class C:

106

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

107

f = classmethod(f)

108

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

109

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

110

its class.

111

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

112

object is passed as the implied first argument.

113

Class methods are different than or Java static methods.

114

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

115

New in version 2.2</description>

116

<param name="functionfunction" optional="0">functionfunction</param>

117

<insert>classmethod(functionfunction)</insert><dialog title="Insert classmethod">classmethod(%0)</dialog><info title="Info window"></info></function>

118

119

120

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

121

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

122

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

123

x > y.</description>

124

125

126

127

128

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

129

executed by an exec statement or evaluated by a call to

130

eval(). The filename argument should

131

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

132

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

133

The kind argument specifies what kind of code must be

134

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

135

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

136

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

137

interactive statement (in the latter case, expression statements

138

that evaluate to something else than None will printed).

139

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

140

endings must be represented by a single newline character

141

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

142

newline character. If line endings are represented by

143

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

144

change them into '\n'.

145

The optional arguments flags and dont_inherit

146

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

147

236) affect the compilation of string. If neither is

148

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

149

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

150

If the flags argument is given and dont_inherit is not

151

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

152

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

153

If dont_inherit is a non-zero integer then the flags

154

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

155

compile are ignored.

156

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

157

together to specify multiple statements. The bitfield required to

158

specify a given feature can be found as the compiler_flag

159

attribute on the _Feature instance in the

160

__future__ module.</description>

161

<param name="string" optional="0">string</param><param name="filename" optional="0">filename</param><param name="kind" optional="0">kind</param><param name="flags" optional="1">flags</param><param name="dont_inherit" optional="1">dont_inherit</param>

162

<insert>compile(string, filename, kind, [flags], [dont_inherit])</insert><dialog title="Insert compile">compile(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

163

164

165

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

166

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

167

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

168

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

169

second parameter can never be a string.

170

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

171

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

172

serves as a numeric conversion function like int(),

173

long() and float(). If both arguments

174

are omitted, returns 0j.</description>

175

176

<insert>complex(real, [imag])</insert><dialog title="Insert complex">complex(%0, %1)</dialog><info title="Info window"></info></function>

177

178

179

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

180

object and a string. The string must be the name

181

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

182

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

183

delattr(x, 'foobar') is equivalent to

184

del x.foobar.</description>

185

<param name="object" optional="0">object</param><param name="name name" optional="0">name name</param>

186

<insert>delattr(object, name name)</insert><dialog title="Insert delattr">delattr(%0, %1)</dialog><info title="Info window"></info></function>

187

188

189

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

190

argument or from a set of keyword arguments.

191

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

192

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

193

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

194

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

195

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

196

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

197

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

198

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

199

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

200

dictionary.

201

If keyword arguments are given, the keywords themselves with their

202

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

203

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

204

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

205

For example, these all return a dictionary equal to

206

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

207

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

208

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

209

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

210

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

211

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

212

dict(one=2, two=3)

213

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

214

New in version 2.2

215

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

216

arguments added</description>

217

<param name="mapping-or-sequence" optional="0">mapping-or-sequence</param>

218

<insert>dict(mapping-or-sequence)</insert><dialog title="Insert dict">dict(%0)</dialog><info title="Info window"></info></function>

219

220

221

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

222

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

223

attributes for that object. This information is gleaned from the

224

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

225

or type object. The list is not necessarily complete.

226

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

227

module's attributes.

228

If the object is a type or class object,

229

the list contains the names of its attributes,

230

and recursively of the attributes of its bases.

231

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

232

the names of its class's attributes,

233

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

234

The resulting list is sorted alphabetically.

235

For example:

236

>>> import struct

237

>>> dir()

238

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

239

>>> dir(struct)

240

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

241

Because dir() is supplied primarily as a convenience

242

for use at an interactive prompt,

243

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

244

supply a rigorously or consistently defined set of names,

245

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

246

<param name="object" optional="0">object</param>

247

<insert>dir(object)</insert><dialog title="Insert dir">dir(%0)</dialog><info title="Info window"></info></function>

248

249

250

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

251

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

252

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

253

plain and long integers, the result is the same as

254

(a / b, a % b).

255

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

256

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

257

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

258

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

259

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

260

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

261

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

262

deprecated</description>

263

264

<insert>divmod(a, b b)</insert><dialog title="Insert divmod">divmod(%0, %1)</dialog><info title="Info window"></info></function>

265

266

267

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

268

iterator, or some other object which supports iteration. The

269

next() method of the iterator returned by

270

enumerate() returns a tuple containing a count (from

271

zero) and the corresponding value obtained from iterating over

272

iterable. enumerate() is useful for obtaining an

273

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

274

seq[2]), ....

275

New in version 2.3</description>

276

<param name="iterableiterable" optional="0">iterableiterable</param>

277

<insert>enumerate(iterableiterable)</insert><dialog title="Insert enumerate">enumerate(%0)</dialog><info title="Info window"></info></function>

278

279

280

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

281

expression argument is parsed and evaluated as a Python

282

expression (technically speaking, a condition list) using the

283

globals and locals dictionaries as global and local name

284

space. If the globals dictionary is present and lacks

285

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

286

expression is parsed. This means that expression

287

normally has full access to the standard

288

__builtin__ module and restricted environments

289

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

290

the globals dictionary. If both dictionaries are omitted, the

291

expression is executed in the environment where eval is

292

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

293

Syntax errors are reported as exceptions. Example:

294

>>> x = 1

295

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

296

2

297

This function can also be used to execute arbitrary code objects

298

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

299

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

300

compiled passing 'eval' as the kind argument.

301

Hints: dynamic execution of statements is supported by the

302

exec statement. Execution of statements from a file is

303

supported by the execfile() function. The

304

globals() and locals() functions returns the

305

current global and local dictionary, respectively, which may be

306

useful to pass around for use by eval() or

307

execfile().</description>

308

<param name="expression" optional="0">expression</param><param name="globals" optional="1">globals</param><param name="locals" optional="1">locals</param>

309

<insert>eval(expression, [globals], [locals])</insert><dialog title="Insert eval">eval(%0, %1, %2)</dialog><info title="Info window"></info></function>

310

311

312

<description>This function is similar to the

313

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

314

is different from the import statement in that it does not

315

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

316

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

317

rarely so does not warrant being made into a statement.

318

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

319

file is parsed and evaluated as a sequence of Python statements

320

(similarly to a module) using the globals and locals

321

dictionaries as global and local namespace. If the locals

322

dictionary is omitted it defaults to the globals dictionary.

323

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

324

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

325

None.

326

The default locals act as described for function

327

locals() below: modifications to the default locals

328

dictionary should not be attempted. Pass an explicit locals

329

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

330

function execfile() returns. execfile() cannot

331

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

332

<param name="filename" optional="0">filename</param><param name="globals" optional="1">globals</param><param name="locals" optional="1">locals</param>

333

<insert>execfile(filename, [globals], [locals])</insert><dialog title="Insert execfile">execfile(%0, %1, %2)</dialog><info title="Info window"></info></function>

334

335

336

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

337

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

338

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

339

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

340

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

341

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

342

regardless of the current seek position).

343

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

344

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

345

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

346

that differentiate between binary and text files (else it is

347

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

348

raised.

349

In addition to the standard fopen() values mode

350

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

351

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

352

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

353

convention,

354

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

355

convention. All of these external representations are seen as

356

'\n'

357

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

358

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

359

file objects so opened also have an attribute called

360

newlines which has a value of None (if no newlines

361

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

362

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

363

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

364

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

365

treat binary and text files differently, where it serves as

366

documentation.)

367

</description>

368

<param name="filename" optional="0">filename</param><param name="mode" optional="1">mode</param><param name="bufsize" optional="1">bufsize</param>

369

<insert>file(filename, [mode], [bufsize])</insert><dialog title="Insert file">file(%0, %1, %2)</dialog><info title="Info window"></info></function>

370

371

372

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

373

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

374

container which supports iteration, or an iterator, If list

375

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

376

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

377

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

378

(zero or empty) are removed.

379

Note that filter(function, list) is equivalent to

380

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

381

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

382

function is None.</description>

383

<param name="function" optional="0">function</param><param name="list list" optional="0">list list</param>

384

<insert>filter(function, list list)</insert><dialog title="Insert filter">filter(%0, %1)</dialog><info title="Info window"></info></function>

385

386

387

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

388

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

389

number, possibly embedded in whitespace; this behaves identical to

390

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

391

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

392

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

393

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

394

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

395

396

<insert>float(x)</insert><dialog title="Insert float">float(%0)</dialog><info title="Info window"></info></function>

397

398

399

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

400

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

401

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

402

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

403

the inner sets should also be frozenset objects. If

404

iterable is not specified, returns a new empty set,

405

frozenset([]).

406

New in version 2.4</description>

407

<param name="iterable" optional="0">iterable</param>

408

<insert>frozenset(iterable)</insert><dialog title="Insert frozenset">frozenset(%0)</dialog><info title="Info window"></info></function>

409

410

411

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

412

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

413

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

414

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

415

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

416

otherwise AttributeError is raised.</description>

417

<param name="object" optional="0">object</param><param name="name" optional="0">name</param><param name="default" optional="1">default</param>

418

<insert>getattr(object, name, [default])</insert><dialog title="Insert getattr">getattr(%0, %1, %2)</dialog><info title="Info window"></info></function>

419

420

421

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

422

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

423

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

424

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

425

426

<insert>globals()</insert><dialog title="Insert globals">globals()</dialog><info title="Info window"></info></function>

427

428

429

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

430

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

431

(This is implemented by calling getattr(object,

432

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

433

<param name="object" optional="0">object</param><param name="name name" optional="0">name name</param>

434

<insert>hasattr(object, name name)</insert><dialog title="Insert hasattr">hasattr(%0, %1)</dialog><info title="Info window"></info></function>

435

436

437

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

438

are integers. They are used to quickly compare dictionary

439

keys during a dictionary lookup. Numeric values that compare equal

440

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

441

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

442

<param name="objectobject" optional="0">objectobject</param>

443

<insert>hash(objectobject)</insert><dialog title="Insert hash">hash(%0)</dialog><info title="Info window"></info></function>

444

445

446

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

447

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

448

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

449

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

450

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

451

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

452

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

453

New in version 2.2</description>

454

<param name="object" optional="0">object</param>

455

<insert>help(object)</insert><dialog title="Insert help">help(%0)</dialog><info title="Info window"></info></function>

456

457

458

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

459

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

460

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

461

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

462

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

463

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

464

raise an OverflowError exception.</description>

465

466

467

468

469

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

470

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

471

object during its lifetime. Two objects whose lifetimes are

472

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

473

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

474

<param name="objectobject" optional="0">objectobject</param>

475

<insert>id(objectobject)</insert><dialog title="Insert id">id(%0)</dialog><info title="Info window"></info></function>

476

477

478

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

479

This function is not safe from user errors! It

480

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

481

syntactically valid, a SyntaxError will be raised.

482

Other exceptions may be raised if there is an error during

483

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

484

need when writing a quick script for expert use.)

485

If the readline module was loaded, then

486

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

487

history features.

488

Consider using the raw_input() function for general input

489

from users.</description>

490

<param name="prompt" optional="0">prompt</param>

491

<insert>input(prompt)</insert><dialog title="Insert input">input(%0)</dialog><info title="Info window"></info></function>

492

493

494

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

495

string, it must contain a possibly signed decimal number

496

representable as a Python integer, possibly embedded in whitespace.

497

The radix parameter gives the base for the

498

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

499

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

500

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

501

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

502

TypeError is raised.

503

Otherwise, the argument may be a plain or

504

long integer or a floating point number. Conversion of floating

505

point numbers to integers truncates (towards zero).

506

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

507

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

508

<param name="x" optional="0">x</param><param name="radix" optional="1">radix</param>

509

<insert>int(x, [radix])</insert><dialog title="Insert int">int(%0, %1)</dialog><info title="Info window"></info></function>

510

511

512

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

513

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

514

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

515

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

516

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

517

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

518

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

519

recursively contain other such tuples (other sequence types are not

520

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

521

classes, types, and such tuples, a TypeError exception

522

is raised.

523

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

524

<param name="object" optional="0">object</param><param name="classinfo classinfo" optional="0">classinfo classinfo</param>

525

<insert>isinstance(object, classinfo classinfo)</insert><dialog title="Insert isinstance">isinstance(%0, %1)</dialog><info title="Info window"></info></function>

526

527

528

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

529

classinfo. A class is considered a subclass of itself.

530

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

531

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

532

TypeError exception is raised.

533

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

534

<param name="class" optional="0">class</param><param name="classinfo classinfo" optional="0">classinfo classinfo</param>

535

<insert>issubclass(class, classinfo classinfo)</insert><dialog title="Insert issubclass">issubclass(%0, %1)</dialog><info title="Info window"></info></function>

536

537

538

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

539

differently depending on the presence of the second argument.

540

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

541

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

542

it must support the sequence protocol (the __getitem__()

543

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

544

support either of those protocols, TypeError is raised.

545

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

546

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

547

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

548

method; if the value returned is equal to sentinel,

549

StopIteration will be raised, otherwise the value will

550

be returned.

551

New in version 2.2</description>

552

<param name="o" optional="0">o</param><param name="sentinel" optional="1">sentinel</param>

553

<insert>iter(o, [sentinel])</insert><dialog title="Insert iter">iter(%0, %1)</dialog><info title="Info window"></info></function>

554

555

556

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

557

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

558

559

560

561

562

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

563

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

564

container that supports iteration, or an iterator object. If

565

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

566

similar to sequence[:]. For instance,

567

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

568

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

569

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

570

<param name="sequence" optional="0">sequence</param>

571

<insert>list(sequence)</insert><dialog title="Insert list">list(%0)</dialog><info title="Info window"></info></function>

572

573

574

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

575

The contents of this dictionary should not be modified;

576

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

577

interpreter.</description>

578

579

<insert>locals()</insert><dialog title="Insert locals">locals()</dialog><info title="Info window"></info></function>

580

581

582

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

583

string, it must contain a possibly signed number of

584

arbitrary size, possibly embedded in whitespace;

585

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

586

radix argument is interpreted in the same way as for

587

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

588

Otherwise, the argument may be a plain or

589

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

590

the same value is returned. Conversion of floating

591

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

592

are given, returns 0L.</description>

593

<param name="x" optional="0">x</param><param name="radix" optional="1">radix</param>

594

<insert>long(x, [radix])</insert><dialog title="Insert long">long(%0, %1)</dialog><info title="Info window"></info></function>

595

596

597

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

598

of the results. If additional list arguments are passed,

599

function must take that many arguments and is applied to the

600

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

601

is assumed to be extended with None items. If function

602

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

603

multiple list arguments, map() returns a list consisting

604

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

605

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

606

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

607

<param name="function" optional="0">function</param><param name="list" optional="0">list</param><param name="... ..." optional="0">... ...</param>

608

<insert>map(function, list, ... ...)</insert><dialog title="Insert map">map(%0, %1, %2)</dialog><info title="Info window"></info></function>

609

610

611

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

612

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

613

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

614

615

616

617

618

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

619

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

620

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

621

622

623

624

625

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

626

to all instances of new style classes.

627

New in version 2.2

628

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

629

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

630

631

<insert>object()</insert><dialog title="Insert object">object()</dialog><info title="Info window"></info></function>

632

633

634

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

635

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

636

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

637

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

638

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

639

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

640

OverflowError exception.</description>

641

642

643

644

645

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

646

<param name="filename" optional="0">filename</param><param name="mode" optional="1">mode</param><param name="bufsize" optional="1">bufsize</param>

647

<insert>open(filename, [mode], [bufsize])</insert><dialog title="Insert open">open(%0, %1, %2)</dialog><info title="Info window"></info></function>

648

649

650

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

651

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

652

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

653

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

654

characters.</description>

655

656

657

658

659

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

660

x to the power y, modulo z (computed more

661

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

662

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

663

coercion rules for binary arithmetic operators apply. For int and

664

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

665

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

666

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

667

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

668

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

669

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

670

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

671

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

672

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

673

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

674

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

675

returned platform-dependent results depending on floating-point

676

rounding accidents.)</description>

677

678

679

680

681

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

682

derive from object).

683

fget is a function for getting an attribute value, likewise

684

fset is a function for setting, and fdel a function

685

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

686

class C(object):

687

def getx(self): return self.__x

688

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

689

def delx(self): del self.__x

690

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

691

New in version 2.2</description>

692

693

<insert>property(fget, [fset], [fdel], [doc])</insert><dialog title="Insert property">property(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

694

695

696

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

697

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

698

arguments must be plain integers. If the step argument is

699

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

700

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

701

plain integers [start, start + step,

702

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

703

the last element is the largest start + i *

704

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

705

element is the largest start + i * step

706

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

707

ValueError is raised). Example:

708

>>> range(10)

709

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

710

>>> range(1, 11)

711

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

712

>>> range(0, 30, 5)

713

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

714

>>> range(0, 10, 3)

715

[0, 3, 6, 9]

716

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

717

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

718

>>> range(0)

719

[]

720

>>> range(1, 0)

721

[]

722

</description>

723

<param name="start" optional="0">start</param><param name="stop" optional="1">stop</param><param name="step" optional="1">step</param>

724

<insert>range(start, [stop], [step])</insert><dialog title="Insert range">range(%0, %1, %2)</dialog><info title="Info window"></info></function>

725

726

727

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

728

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

729

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

730

When is read, EOFError is raised. Example:

731

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

732

--> Monty Python's Flying Circus

733

>>> s

734

"Monty Python's Flying Circus"

735

If the readline module was loaded, then

736

raw_input() will use it to provide elaborate

737

line editing and history features.</description>

738

<param name="prompt" optional="0">prompt</param>

739

<insert>raw_input(prompt)</insert><dialog title="Insert raw_input">raw_input(%0)</dialog><info title="Info window"></info></function>

740

741

742

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

743

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

744

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

745

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

746

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

747

is the update value from the sequence. If the optional

748

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

749

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

750

sequence is empty. If initializer is not given and

751

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

752

<param name="function" optional="0">function</param><param name="sequence" optional="0">sequence</param><param name="initializer" optional="1">initializer</param>

753

<insert>reduce(function, sequence, [initializer])</insert><dialog title="Insert reduce">reduce(%0, %1, %2)</dialog><info title="Info window"></info></function>

754

755

756

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

757

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

758

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

759

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

760

version without leaving the Python interpreter. The return value is

761

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

762

There are a number of caveats:

763

If a module is syntactically correct but its initialization fails,

764

the first import statement for it does not bind its name

765

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

766

sys.modules. To reload the module you must first

767

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

768

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

769

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

770

global variables) is retained. Redefinitions of names will override

771

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

772

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

773

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

774

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

775

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

776

table's presence and skip its initialization if desired.

777

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

778

dynamically loaded modules, except for sys,

779

__main__ and __builtin__. In

780

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

781

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

782

reloaded.

783

If a module imports objects from another module using from

784

import , calling reload() for

785

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

786

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

787

another is to use import and qualified names

788

(module.name) instead.

789

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

790

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

791

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

792

same is true for derived classes.</description>

793

<param name="modulemodule" optional="0">modulemodule</param>

794

<insert>reload(modulemodule)</insert><dialog title="Insert reload">reload(%0)</dialog><info title="Info window"></info></function>

795

796

797

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

798

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

799

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

800

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

801

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

802

when passed to eval().</description>

803

<param name="objectobject" optional="0">objectobject</param>

804

<insert>repr(objectobject)</insert><dialog title="Insert repr">repr(%0)</dialog><info title="Info window"></info></function>

805

806

807

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

808

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

809

__getitem__() method with integer arguments starting at

810

0).

811

New in version 2.4</description>

812

<param name="seqseq" optional="0">seqseq</param>

813

<insert>reversed(seqseq)</insert><dialog title="Insert reversed">reversed(%0)</dialog><info title="Info window"></info></function>

814

815

816

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

817

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

818

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

819

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

820

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

821

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

822

823

<insert>round(x, [n])</insert><dialog title="Insert round">round(%0, %1)</dialog><info title="Info window"></info></function>

824

825

826

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

827

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

828

be frozenset objects. If iterable is not specified,

829

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

830

New in version 2.4</description>

831

<param name="iterable" optional="0">iterable</param>

832

<insert>set(iterable)</insert><dialog title="Insert set">set(%0)</dialog><info title="Info window"></info></function>

833

834

835

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

836

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

837

existing attribute or a new attribute. The function assigns the

838

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

839

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

840

x.foobar = 123.</description>

841

<param name="object" optional="0">object</param><param name="name" optional="0">name</param><param name="value value" optional="0">value value</param>

842

<insert>setattr(object, name, value value)</insert><dialog title="Insert setattr">setattr(%0, %1, %2)</dialog><info title="Info window"></info></function>

843

844

845

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

846

range(start, stop, step). The start

847

and step arguments default to None. Slice objects have

848

read-only data attributes start, stop and

849

step which merely return the argument values (or their

850

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

851

are used by Numerical Python</description>

852

<param name="start" optional="0">start</param><param name="stop" optional="1">stop</param><param name="step" optional="1">step</param>

853

<insert>slice(start, [stop], [step])</insert><dialog title="Insert slice">slice(%0, %1, %2)</dialog><info title="Info window"></info></function>

854

855

856

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

857

The optional arguments cmp, key, and reverse

858

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

859

New in version 2.4</description>

860

<param name="iterable" optional="0">iterable</param><param name="cmp" optional="1" default="None">cmp</param><param name="key" optional="1" default="None">key</param><param name="reverse" optional="1" default="False">reverse</param>

861

<insert>sorted(iterable, [cmp=None], [key=None], [reverse=False])</insert><dialog title="Insert sorted">sorted(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

862

863

864

<description>Return a static method for function.

865

A static method does not receive an implicit first argument.

866

To declare a static method, use this idiom:

867

class C:

868

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

869

f = staticmethod(f)

870

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

871

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

872

for its class.

873

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

874

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

875

section.

876

New in version 2.2</description>

877

<param name="functionfunction" optional="0">functionfunction</param>

878

<insert>staticmethod(functionfunction)</insert><dialog title="Insert staticmethod">staticmethod(%0)</dialog><info title="Info window"></info></function>

879

880

881

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

882

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

883

difference with repr(object) is that

884

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

885

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

886

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

887

string, ''.</description>

888

<param name="object" optional="0">object</param>

889

<insert>str(object)</insert><dialog title="Insert str">str(%0)</dialog><info title="Info window"></info></function>

890

891

892

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

893

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

894

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

895

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

896

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

897

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

898

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

899

New in version 2.3</description>

900

<param name="sequence" optional="0">sequence</param><param name="start" optional="1">start</param>

901

<insert>sum(sequence, [start])</insert><dialog title="Insert sum">sum(%0, %1)</dialog><info title="Info window"></info></function>

902

903

904

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

905

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

906

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

907

the second argument is a type, issubclass(type2,

908

type) must be true.

909

super() only works for new-style classes.

910

A typical use for calling a cooperative superclass method is:

911

class C(B):

912

def meth(self, arg):

913

super(C, self).meth(arg)

914

New in version 2.2</description>

915

<param name="type" optional="0">type</param><param name="object-or-type" optional="1">object-or-type</param>

916

<insert>super(type, [object-or-type])</insert><dialog title="Insert super">super(%0, %1)</dialog><info title="Info window"></info></function>

917

918

919

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

920

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

921

container that supports iteration, or an iterator object.

922

If sequence is already a tuple, it

923

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

924

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

925

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

926

tuple, ().</description>

927

<param name="sequence" optional="0">sequence</param>

928

<insert>tuple(sequence)</insert><dialog title="Insert tuple">tuple(%0)</dialog><info title="Info window"></info></function>

929

930

931

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

932

typetype object. The standard module

933

typestypes defines names for all built-in

934

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

935

For instance:

936

>>> import types

937

>>> x = 'abc'

938

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

939

...

940

It's a string

941

>>> def f(): pass

942

...

943

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

944

...

945

It's a function

946

The isinstance() built-in function is recommended for

947

testing the type of an object.</description>

948

<param name="objectobject" optional="0">objectobject</param>

949

<insert>type(objectobject)</insert><dialog title="Insert type">type(%0)</dialog><info title="Info window"></info></function>

950

951

952

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

953

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

954

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

955

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

956

ValueError is raised otherwise.

957

New in version 2.0</description>

958

959

<insert>unichr(ii)</insert><dialog title="Insert unichr">unichr(%0)</dialog><info title="Info window"></info></function>

960

961

962

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

963

following modes:

964

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

965

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

966

character buffer using the codec for encoding. The

967

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

968

if the encoding is not known, LookupError is raised.

969

Error handling is done according to errors; this specifies the

970

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

971

errors is 'strict' (the default), a

972

ValueError is raised on errors, while a value of

973

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

974

'replace' causes the official Unicode replacement character,

975

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

976

be decoded. See also the codecs module.

977

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

978

behaviour of str() except that it returns Unicode strings

979

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

980

Unicode string or subclass it will return that Unicode string without

981

any additional decoding applied.

982

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

983

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

984

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

985

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

986

the default encoding in 'strict' mode.

987

New in version 2.0

988

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

989

<param name="object" optional="0">object</param><param name="encoding" optional="1">encoding</param><param name="errors" optional="1">errors</param>

990

<insert>unicode(object, [encoding], [errors])</insert><dialog title="Insert unicode">unicode(%0, %1, %2)</dialog><info title="Info window"></info></function>

991

992

993

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

994

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

995

as argument (or anything else that has a __dict__

996

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

997

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

998

effects on the corresponding symbol table are undefined.

999

In the current implementation, local variable bindings cannot

1000

normally be affected this way, but variables retrieved from

1001

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

1002

<param name="object" optional="0">object</param>

1003

<insert>vars(object)</insert><dialog title="Insert vars">vars(%0)</dialog><info title="Info window"></info></function>

1004

1005

1006

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

1007

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

1008

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

1009

actually storing them all simultaneously. The advantage of

1010

xrange() over range() is minimal (since

1011

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

1012

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

1013

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

1014

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

1015

<param name="start" optional="0">start</param><param name="stop" optional="1">stop</param><param name="step" optional="1">step</param>

1016

<insert>xrange(start, [stop], [step])</insert><dialog title="Insert xrange">xrange(%0, %1, %2)</dialog><info title="Info window"></info></function>

1017

1018

1019

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

1020

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

1021

The returned list is truncated in length to the length of

1022

the shortest argument sequence. When there are multiple argument

1023

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

1024

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

1025

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

1026

With no arguments, it returns an empty list.

1027

New in version 2.0

1028

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

1029

and zip() raised a TypeError instead of returning

1030

an empty list.</description>

1031

<param name="seq1" optional="0">seq1</param><param name="moreargs" optional="1">moreargs</param>

1032

<insert>zip(seq1, [moreargs])</insert><dialog title="Insert zip">zip(%0, %1)</dialog><info title="Info window"></info></function>

1033

1034

1035

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

1036

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

1037

the args argument must be a sequence. The function is

1038

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

1039

is the length of the tuple.

1040

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

1041

dictionary whose keys are strings. It specifies keyword arguments

1042

to be added to the end of the argument list.

1043

Calling apply() is different from just calling

1044

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

1045

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

1046

to function(*args, **keywords).

1047

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

1048

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

1049

2.3{Use the extended call syntax instead, as described

1050

above.}</description>

1051

<param name="function" optional="0">function</param><param name="args" optional="0">args</param><param name="keywords" optional="1">keywords</param>

1052

<insert>apply(function, args, [keywords])</insert><dialog title="Insert apply">apply(%0, %1, %2)</dialog><info title="Info window"></info></function>

1053

1054

1055

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

1056

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

1057

object will be created which references the object argument.

1058

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

1059

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

1060

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

1061

argument).</description>

1062

<param name="object" optional="0">object</param><param name="offset" optional="1">offset</param><param name="size" optional="1">size</param>

1063

<insert>buffer(object, [offset], [size])</insert><dialog title="Insert buffer">buffer(%0, %1, %2)</dialog><info title="Info window"></info></function>

1064

1065

1066

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

1067

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

1068

operations.</description>

1069

1070

<insert>coerce(x, y y)</insert><dialog title="Insert coerce">coerce(%0, %1)</dialog><info title="Info window"></info></function>

1071

1072

1073

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

1074

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

1075

Interning strings is useful to gain a little performance on

1076

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

1077

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

1078

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

1079

the names used in Python programs are automatically interned, and

1080

the dictionaries used to hold module, class or instance attributes

1081

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

1082

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

1083

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

1084

around to benefit from it</description>

1085

<param name="stringstring" optional="0">stringstring</param>

1086

<insert>intern(stringstring)</insert><dialog title="Insert intern">intern(%0)</dialog><info title="Info window"></info></function>

1087

1088

</group>

1089

1090

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

1091

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

1092

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

1093

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

1094

release this situation has started to change, although the intended

1095

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

1096

complete.

1097

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

1098

classes, instances and exceptions.

1099

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

1100

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

1101

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

1102

conversion is implicitly used when an object is written by the

1103

printprint statement.

1104

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

1105

and other language statements can be found in the

1106

Python Reference Manual and the

1107

Python Tutorial.)

1108

</description>

1109

1110

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

1111

while condition or as operand of the Boolean operations below.

1112

The following values are considered false:

1113

if

1114

while

1115

</description>

1116

</group>

1117

1118

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

1119

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

1120

x or y

1121

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

1122

x and y

1123

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

1124

not x

1125

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

1126

and

1127

or

1128

not

1129

Notes:

1130

[(1)]

1131

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

1132

[(2)]

1133

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

1134

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

1135

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

1136

</description>

1137

</group>

1138

1139

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

1140

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

1141

Comparisons can be chained arbitrarily; for example, x <

1142

y <= z is equivalent to x < y and

1143

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

1144

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

1145

y is found to be false).

1146

This table summarizes the comparison operations:

1147

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

1148

<{strictly less than}{}

1149

<={less than or equal}{}

1150

>{strictly greater than}{}

1151

>={greater than or equal}{}

1152

=={equal}{}

1153

!={not equal}{(1)}

1154

<>{not equal}{(1)}

1155

is{object identity}{}

1156

is not{negated object identity}{}

1157

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

1158

is

1159

is not

1160

Notes:

1161

[(1)]

1162

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

1163

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

1164

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

1165

compare equal; such objects are ordered consistently but arbitrarily

1166

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

1167

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

1168

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

1169

unequal. Again, such objects are ordered arbitrarily but

1170

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

1171

operators will raise a TypeError exception when any operand

1172

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

1173

(instance method){__cmp__()}

1174

defines the __cmp__() method. Refer to the

1175

Python Reference Manual for

1176

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

1177

Implementation note: Objects of different types except

1178

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

1179

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

1180

Two more operations with the same syntactic priority,

1181

inin and not innot in, are supported

1182

only by sequence types (below).

1183

</description>

1184

</group>

1185

1186

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

1187

long integers, floating point numbers, and complex numbers.

1188

In addition, Booleans are a subtype of plain integers.

1189

Plain integers (also just called integers)

1190

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

1191

bits of precision. Long integers have unlimited precision. Floating

1192

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

1193

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

1194

working with.

1195

numeric

1196

Boolean

1197

integer

1198

long integer

1199

floating point

1200

complex number

1201

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

1202

implemented using double in C. To extract these parts from

1203

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

1204

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

1205

functions and operators. Unadorned integer literals (including hex

1206

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

1207

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

1208

they yield a long integer. Integer literals with an

1209

L or l suffix yield long integers

1210

(L is preferred because 1l looks too much like

1211

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

1212

sign yield floating point numbers. Appending j or

1213

J to a numeric literal yields a complex number with a

1214

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

1215

an imaginary part.

1216

long{integer}{literals}

1217

Python fully supports mixed arithmetic: when a binary arithmetic

1218

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

1219

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

1220

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

1221

narrower than complex.

1222

Comparisons between numbers of mixed type use the same rule.

1223

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

1224

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

1225

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

1226

and complex() can be used

1227

to produce numbers of a specific type.

1228

</description>

1229

</group>

1230

1231

<description>New in version 2.2

1232

</description>

1233

1234

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

1235

iterator protocol described below. If a container supports

1236

different types of iteration, additional methods can be provided to

1237

specifically request iterators for those iteration types. (An

1238

example of an object supporting multiple forms of iteration would be

1239

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

1240

traversal.) This method corresponds to the tp_iter slot of

1241

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

1242

1243

1244

1245

1246

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

1247

containers and iterators to be used with the for and

1248

in statements. This method corresponds to the

1249

tp_iter slot of the type structure for Python objects in

1250

the Python/C API.</description>

1251

1252

1253

1254

1255

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

1256

items, raise the StopIteration exception. This method

1257

corresponds to the tp_iternext slot of the type structure

1258

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

1259

1260

1261

1262

</group>

1263

1264

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

1265

tuples, buffers, and xrange objects.

1266

String literals are written in single or double quotes:

1267

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

1268

Python Reference Manual for more about

1269

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

1270

specified in the syntax using a preceeding u character:

1271

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

1272

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

1273

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

1274

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

1275

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

1276

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

1277

sequence

1278

string

1279

Unicode

1280

tuple

1281

list

1282

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

1283

created by calling the builtin function

1284

buffer().buffer They don't support

1285

concatenation or repetition.

1286

buffer

1287

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

1288

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

1289

function.xrange They don't support slicing,

1290

concatenation or repetition, and using in, not in,

1291

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

1292

xrange

1293

Most sequence types support the following operations. The in and

1294

not in operations have the same priorities as the comparison

1295

operations. The + and * operations have the same

1296

priority as the corresponding numeric operations.They must

1297

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

1298

This table lists the sequence operations sorted in ascending priority

1299

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

1300

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

1301

and j are integers:

1302

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

1303

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

1304

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

1305

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

1306

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

1307

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

1308

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

1309

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

1310

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

1311

len(s){length of s}{}

1312

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

1313

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

1314

operations on{sequence}{types}

1315

len

1316

min

1317

max

1318

in

1319

not in

1320

Notes:

1321

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

1322

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

1323

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

1324

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

1325

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

1326

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

1327

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

1328

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

1329

>>> lists = [[]] * 3

1330

>>> lists

1331

[[], [], []]

1332

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

1333

>>> lists

1334

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

1335

What has happened is that lists is a list containing three

1336

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

1337

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

1338

create a list of different lists this way:

1339

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

1340

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

1341

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

1342

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

1343

>>> lists

1344

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

1345

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

1346

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

1347

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

1348

still 0.

1349

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

1350

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

1351

k < j. If i or j is greater than

1352

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

1353

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

1354

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

1355

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

1356

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

1357

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

1358

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

1359

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

1360

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

1361

be zero.

1362

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

1363

objects support:

1364

</description>

1365

1366

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

1367

1368

<insert>capitalize()</insert><dialog title="Insert capitalize">capitalize()</dialog><info title="Info window"></info></function>

1369

1370

1371

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

1372

using the specified fillchar (default is a space).

1373

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

1374

<param name="width" optional="0">width</param><param name="fillchar" optional="1">fillchar</param>

1375

<insert>center(width, [fillchar])</insert><dialog title="Insert center">center(%0, %1)</dialog><info title="Info window"></info></function>

1376

1377

1378

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

1379

S[start:end]. Optional arguments start and

1380

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

1381

<param name="sub" optional="0">sub</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

1382

<insert>count(sub, [start], [end])</insert><dialog title="Insert count">count(%0, %1, %2)</dialog><info title="Info window"></info></function>

1383

1384

1385

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

1386

encoding defaults to the default string encoding. errors

1387

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

1388

'strict', meaning that encoding errors raise

1389

ValueError. Other possible values are 'ignore' and

1390

'replace'.

1391

New in version 2.2</description>

1392

<param name="encoding" optional="0">encoding</param><param name="errors" optional="1">errors</param>

1393

<insert>decode(encoding, [errors])</insert><dialog title="Insert decode">decode(%0, %1)</dialog><info title="Info window"></info></function>

1394

1395

1396

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

1397

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

1398

error handling scheme. The default for errors is

1399

'strict', meaning that encoding errors raise a

1400

ValueError. Other possible values are 'ignore' and

1401

'replace'.

1402

New in version 2.0</description>

1403

<param name="encoding" optional="0">encoding</param><param name="errors" optional="1">errors</param>

1404

<insert>encode(encoding, [errors])</insert><dialog title="Insert encode">encode(%0, %1)</dialog><info title="Info window"></info></function>

1405

1406

1407

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

1408

otherwise return False. With optional start, test beginning at

1409

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

1410

<param name="suffix" optional="0">suffix</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

1411

<insert>endswith(suffix, [start], [end])</insert><dialog title="Insert endswith">endswith(%0, %1, %2)</dialog><info title="Info window"></info></function>

1412

1413

1414

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

1415

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

1416

characters is assumed.</description>

1417

<param name="tabsize" optional="0">tabsize</param>

1418

<insert>expandtabs(tabsize)</insert><dialog title="Insert expandtabs">expandtabs(%0)</dialog><info title="Info window"></info></function>

1419

1420

1421

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

1422

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

1423

end). Optional arguments start and end are

1424

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

1425

not found.</description>

1426

<param name="sub" optional="0">sub</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

1427

<insert>find(sub, [start], [end])</insert><dialog title="Insert find">find(%0, %1, %2)</dialog><info title="Info window"></info></function>

1428

1429

1430

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

1431

substring is not found.</description>

1432

<param name="sub" optional="0">sub</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

1433

<insert>index(sub, [start], [end])</insert><dialog title="Insert index">index(%0, %1, %2)</dialog><info title="Info window"></info></function>

1434

1435

1436

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

1437

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

1438

1439

<insert>isalnum()</insert><dialog title="Insert isalnum">isalnum()</dialog><info title="Info window"></info></function>

1440

1441

1442

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

1443

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

1444

1445

<insert>isalpha()</insert><dialog title="Insert isalpha">isalpha()</dialog><info title="Info window"></info></function>

1446

1447

1448

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

1449

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

1450

1451

<insert>isdigit()</insert><dialog title="Insert isdigit">isdigit()</dialog><info title="Info window"></info></function>

1452

1453

1454

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

1455

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

1456

1457

<insert>islower()</insert><dialog title="Insert islower">islower()</dialog><info title="Info window"></info></function>

1458

1459

1460

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

1461

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

1462

1463

<insert>isspace()</insert><dialog title="Insert isspace">isspace()</dialog><info title="Info window"></info></function>

1464

1465

1466

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

1467

character, for example uppercase characters may only follow uncased

1468

characters and lowercase characters only cased ones. Return false

1469

otherwise.</description>

1470

1471

<insert>istitle()</insert><dialog title="Insert istitle">istitle()</dialog><info title="Info window"></info></function>

1472

1473

1474

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

1475

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

1476

1477

<insert>isupper()</insert><dialog title="Insert isupper">isupper()</dialog><info title="Info window"></info></function>

1478

1479

1480

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

1481

sequence seq. The separator between elements is the string

1482

providing this method.</description>

1483

<param name="seqseq" optional="0">seqseq</param>

1484

<insert>join(seqseq)</insert><dialog title="Insert join">join(%0)</dialog><info title="Info window"></info></function>

1485

1486

1487

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

1488

Padding is done using the specified fillchar (default is a

1489

space). The original string is returned if

1490

width is less than len(s).

1491

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

1492

<param name="width" optional="0">width</param><param name="fillchar" optional="1">fillchar</param>

1493

<insert>ljust(width, [fillchar])</insert><dialog title="Insert ljust">ljust(%0, %1)</dialog><info title="Info window"></info></function>

1494

1495

1496

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

1497

1498

<insert>lower()</insert><dialog title="Insert lower">lower()</dialog><info title="Info window"></info></function>

1499

1500

1501

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

1502

chars is omitted or None, whitespace characters are

1503

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

1504

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

1505

the string this method is called on.

1506

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

1507

<param name="chars" optional="0">chars</param>

1508

<insert>lstrip(chars)</insert><dialog title="Insert lstrip">lstrip(%0)</dialog><info title="Info window"></info></function>

1509

1510

1511

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

1512

old replaced by new. If the optional argument

1513

count is given, only the first count occurrences are

1514

replaced.</description>

1515

<param name="old" optional="0">old</param><param name="new" optional="0">new</param><param name="count" optional="1">count</param>

1516

<insert>replace(old, new, [count])</insert><dialog title="Insert replace">replace(%0, %1, %2)</dialog><info title="Info window"></info></function>

1517

1518

1519

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

1520

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

1521

arguments start and end are interpreted as in slice

1522

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

1523

<param name="sub" optional="0">sub</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

1524

<insert>rfind(sub, [start], [end])</insert><dialog title="Insert rfind">rfind(%0, %1, %2)</dialog><info title="Info window"></info></function>

1525

1526

1527

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

1528

substring sub is not found.</description>

1529

<param name="sub" optional="0">sub</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

1530

<insert>rindex(sub, [start], [end])</insert><dialog title="Insert rindex">rindex(%0, %1, %2)</dialog><info title="Info window"></info></function>

1531

1532

1533

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

1534

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

1535

The original string is returned if

1536

width is less than len(s).

1537

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

1538

<param name="width" optional="0">width</param><param name="fillchar" optional="1">fillchar</param>

1539

<insert>rjust(width, [fillchar])</insert><dialog title="Insert rjust">rjust(%0, %1)</dialog><info title="Info window"></info></function>

1540

1541

1542

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

1543

delimiter string. If maxsplit is given, at most maxsplit

1544

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

1545

or None, any whitespace string is a separator.

1546

New in version 2.4</description>

1547

<param name="sep" optional="0">sep</param><param name="maxsplit" optional="1">maxsplit</param>

1548

<insert>rsplit(sep, [maxsplit])</insert><dialog title="Insert rsplit">rsplit(%0, %1)</dialog><info title="Info window"></info></function>

1549

1550

1551

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

1552

chars is omitted or None, whitespace characters are

1553

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

1554

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

1555

string this method is called on.

1556

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

1557

<param name="chars" optional="0">chars</param>

1558

<insert>rstrip(chars)</insert><dialog title="Insert rstrip">rstrip(%0)</dialog><info title="Info window"></info></function>

1559

1560

1561

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

1562

delimiter string. If maxsplit is given, at most maxsplit

1563

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

1564

whitespace string is a separator.</description>

1565

<param name="sep" optional="0">sep</param><param name="maxsplit" optional="1">maxsplit</param>

1566

<insert>split(sep, [maxsplit])</insert><dialog title="Insert split">split(%0, %1)</dialog><info title="Info window"></info></function>

1567

1568

1569

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

1570

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

1571

keepends is given and true.</description>

1572

<param name="keepends" optional="0">keepends</param>

1573

<insert>splitlines(keepends)</insert><dialog title="Insert splitlines">splitlines(%0)</dialog><info title="Info window"></info></function>

1574

1575

1576

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

1577

return False. With optional start, test string beginning at

1578

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

1579

position.</description>

1580

<param name="prefix" optional="0">prefix</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

1581

<insert>startswith(prefix, [start], [end])</insert><dialog title="Insert startswith">startswith(%0, %1, %2)</dialog><info title="Info window"></info></function>

1582

1583

1584

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

1585

removed. If chars is omitted or None, whitespace

1586

characters are removed. If given and not None, chars

1587

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

1588

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

1589

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

1590

<param name="chars" optional="0">chars</param>

1591

<insert>strip(chars)</insert><dialog title="Insert strip">strip(%0)</dialog><info title="Info window"></info></function>

1592

1593

1594

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

1595

lowercase and vice versa.</description>

1596

1597

<insert>swapcase()</insert><dialog title="Insert swapcase">swapcase()</dialog><info title="Info window"></info></function>

1598

1599

1600

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

1601

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

1602

1603

<insert>title()</insert><dialog title="Insert title">title()</dialog><info title="Info window"></info></function>

1604

1605

1606

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

1607

optional argument deletechars are removed, and the remaining

1608

characters have been mapped through the given translation table, which

1609

must be a string of length 256.

1610

For Unicode objects, the translate() method does not

1611

accept the optional deletechars argument. Instead, it

1612

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

1613

through the given translation table which must be a mapping of

1614

Unicode ordinals to Unicode ordinals, Unicode strings or None.

1615

Unmapped characters are left untouched. Characters mapped to None

1616

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

1617

character mapping codec using the codecs module (see

1618

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

1619

<param name="table" optional="0">table</param><param name="deletechars" optional="1">deletechars</param>

1620

<insert>translate(table, [deletechars])</insert><dialog title="Insert translate">translate(%0, %1)</dialog><info title="Info window"></info></function>

1621

1622

1623

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

1624

1625

<insert>upper()</insert><dialog title="Insert upper">upper()</dialog><info title="Info window"></info></function>

1626

1627

1628

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

1629

of length width. The original string is returned if

1630

width is less than len(s).

1631

New in version 2.2.2</description>

1632

<param name="widthwidth" optional="0">widthwidth</param>

1633

<insert>zfill(widthwidth)</insert><dialog title="Insert zfill">zfill(%0)</dialog><info title="Info window"></info></function>

1634

1635

</group>

1636

1637

<description>set

1638

A set object is an unordered collection of immutable values.

1639

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

1640

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

1641

and symmetric difference.

1642

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

1643

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

1644

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

1645

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

1646

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

1647

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

1648

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

1649

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

1650

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

1651

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

1652

a dictionary key or as an element of another set.

1653

Instances of set and frozenset provide the following operations:

1654

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

1655

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

1656

x in s{}

1657

{test x for membership in s}

1658

x not in s{}

1659

{test x for non-membership in s}

1660

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

1661

{test whether every element in s is in t}

1662

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

1663

{test whether every element in t is in s}

1664

s.union(t){s | t}

1665

{new set with elements from both s and t}

1666

s.intersection(t){s t}

1667

{new set with elements common to s and t}

1668

s.difference(t){s - t}

1669

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

1670

s.symmetric_difference(t){s t}

1671

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

1672

s.copy(){}

1673

{new set with a shallow copy of s}

1674

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

1675

difference(), and symmetric_difference(),

1676

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

1677

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

1678

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

1679

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

1680

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

1681

Both set and frozenset support set to set comparisons.

1682

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

1683

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

1684

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

1685

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

1686

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

1687

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

1688

The subset and equality comparisons do not generalize to a complete

1689

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

1690

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

1691

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

1692

a>b.

1693

Accordingly, sets do not implement the __cmp__ method.

1694

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

1695

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

1696

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

1697

remove(), and discard() methods automatically match

1698

instances of the set class their frozenset counterparts

1699

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

1700

returns True.

1701

The following table lists operations available for set

1702

that do not apply to immutable instances of frozenset:

1703

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

1704

s.update(t)

1705

{s |= t}

1706

{return set s with elements added from t}

1707

s.intersection_update(t)

1708

{s t}

1709

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

1710

s.difference_update(t)

1711

{s -= t}

1712

{return set s after removing elements found in t}

1713

s.symmetric_difference_update(t)

1714

{s = t}

1715

{return set s with elements from s or t

1716

but not both}

1717

s.add(x){}

1718

{add element x to set s}

1719

s.remove(x){}

1720

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

1721

s.discard(x){}

1722

{removes x from set s if present}

1723

s.pop(){}

1724

{remove and return an arbitrary element from s; raises

1725

KeyError if empty}

1726

s.clear(){}

1727

{remove all elements from set s}

1728

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

1729

intersection_update(), difference_update(), and

1730

symmetric_difference_update() methods will accept any iterable

1731

as an argument.

1732

</description>

1733

</group>

1734

1735

<description>mapping

1736

dictionary

1737

A mapping object maps immutable values to

1738

arbitrary objects. Mappings are mutable objects. There is currently

1739

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

1740

almost arbitrary values. Only values containing lists, dictionaries

1741

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

1742

object identity) may not be used as keys.

1743

Numeric types used for keys obey the normal rules for numeric

1744

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

1745

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

1746

dictionary entry.

1747

Dictionaries are created by placing a comma-separated list of

1748

key: value pairs within braces, for example:

1749

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

1750

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

1751

The following operations are defined on mappings (where a and

1752

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

1753

arbitrary objects):

1754

operations on{mapping}{types}

1755

operations on{dictionary}{type}

1756

del

1757

len

1758

(dictionary method){

1759

clear()

1760

copy()

1761

has_key()

1762

fromkeys() items()

1763

keys()

1764

update()

1765

values()

1766

get()

1767

setdefault()

1768

pop()

1769

popitem()

1770

iteritems()

1771

iterkeys()

1772

itervalues()}

1773

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

1774

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

1775

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

1776

a[k] = v

1777

{set a[k] to v}

1778

{}

1779

del a[k]

1780

{remove a[k] from a}

1781

{(1)}

1782

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

1783

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

1784

a.has_key(k)

1785

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

1786

{}

1787

k in a

1788

{Equivalent to a.has_key(k)}

1789

{(2)}

1790

k not in a

1791

{Equivalent to not a.has_key(k)}

1792

{(2)}

1793

a.items()

1794

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

1795

{(3)}

1796

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

1797

a.update(b)

1798

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

1799

{}

1800

a.fromkeys(seq, value)

1801

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

1802

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

1803

a.get(k, x)

1804

{a[k] if k in a,

1805

else x}

1806

{(4)}

1807

a.setdefault(k, x)

1808

{a[k] if k in a,

1809

else x (also setting it)}

1810

{(5)}

1811

a.pop(k, x)

1812

{a[k] if k in a,

1813

else x (and remove k)}

1814

{(8)}

1815

a.popitem()

1816

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

1817

{(6)}

1818

a.iteritems()

1819

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

1820

{(2), (3)}

1821

a.iterkeys()

1822

{return an iterator over the mapping's keys}

1823

{(2), (3)}

1824

a.itervalues()

1825

{return an iterator over the mapping's values}

1826

{(2), (3)}

1827

Notes:

1828

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

1829

in the map.

1830

[(2)] New in version 2.2

1831

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

1832

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

1833

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

1834

are called with no intervening modifications to the dictionary, the

1835

lists will directly correspond. This allows the creation of

1836

(value, key) pairs using zip():

1837

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

1838

relationship holds for the iterkeys() and

1839

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

1840

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

1841

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

1842

v) in a.iteritems()].

1843

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

1844

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

1845

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

1846

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

1847

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

1848

the dictionary as the value of k.

1849

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

1850

over a dictionary, as often used in set algorithms.

1851

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

1852

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

1853

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

1854

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

1855

</description>

1856

</group>

1857

1858

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

1859

package and can be created with the built-in constructor

1860

file()file described in section

1861

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

1862

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

1863

alias for file().

1864

File objects are also returned

1865

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

1866

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

1867

makefile() method of socket objects.

1868

os

1869

socket

1870

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

1871

IOError is raised. This includes situations where the

1872

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

1873

device or writing a file opened for reading.

1874

Files have the following methods:

1875

</description>

1876

1877

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

1878

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

1879

ValueError after the file has been closed. Calling

1880

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

1881

1882

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

1883

1884

1885

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

1886

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

1887

objects.</description>

1888

1889

<insert>flush()</insert><dialog title="Insert flush">flush()</dialog><info title="Info window"></info></function>

1890

1891

1892

1893

1894

<insert>fileno()</insert><dialog title="Insert fileno">fileno()</dialog><info title="Info window"></info></function>

1895

1896

1897

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

1898

False. If a file-like object is not associated

1899

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

1900

1901

<insert>isatty()</insert><dialog title="Insert isatty">isatty()</dialog><info title="Info window"></info></function>

1902

1903

1904

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

1905

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

1906

iterator, typically in a for loop (for example,

1907

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

1908

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

1909

StopIteration when is hit. In order to make a

1910

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

1911

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

1912

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

1913

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

1914

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

1915

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

1916

flush the read-ahead buffer.

1917

New in version 2.3</description>

1918

1919

1920

1921

1922

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

1923

before obtaining size bytes). If the size

1924

argument is negative or omitted, read all data until is

1925

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

1926

string is returned when is encountered immediately. (For

1927

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

1928

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

1929

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

1930

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

1931

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

1932

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

1933

1934

1935

1936

1937

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

1938

kept in the string

1939

The advantage of leaving the newline on is that

1940

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

1941

matter, for example, if you

1942

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

1943

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

1944

or not (yes this happens!).

1945

(but may be absent when a file ends with an

1946

incomplete line). If the size argument is present and

1947

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

1948

newline) and an incomplete line may be returned.

1949

An empty string is returned only when is encountered

1950

immediately. Unlike stdio's fgets(), the

1951

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

1952

occurred in the input.</description>

1953

1954

<insert>readline(size)</insert><dialog title="Insert readline">readline(%0)</dialog><info title="Info window"></info></function>

1955

1956

1957

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

1958

the lines thus read. If the optional sizehint argument is

1959

present, instead of reading up to , whole lines totalling

1960

approximately sizehint bytes (possibly after rounding up to an

1961

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

1962

interface may choose to ignore sizehint if it cannot be

1963

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

1964

<param name="sizehint" optional="0">sizehint</param>

1965

<insert>readlines(sizehint)</insert><dialog title="Insert readlines">readlines(%0)</dialog><info title="Info window"></info></function>

1966

1967

1968

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

1969

New in version 2.1

1970

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

1971

1972

<insert>xreadlines()</insert><dialog title="Insert xreadlines">xreadlines()</dialog><info title="Info window"></info></function>

1973

1974

1975

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

1976

The whence argument is optional and defaults to 0

1977

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

1978

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

1979

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

1980

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

1981

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

1982

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

1983

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

1984

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

1985

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

1986

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

1987

behavior.

1988

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

1989

<param name="offset" optional="0">offset</param><param name="whence" optional="1">whence</param>

1990

<insert>seek(offset, [whence])</insert><dialog title="Insert seek">seek(%0, %1)</dialog><info title="Info window"></info></function>

1991

1992

1993

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

1994

ftell().</description>

1995

1996

1997

1998

1999

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

2000

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

2001

defaults to the current position. The current file position is

2002

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

2003

current size, the result is platform-dependent: possibilities

2004

include that file may remain unchanged, increase to the specified

2005

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

2006

undefined new content.

2007

Availability: Windows, many variants.</description>

2008

2009

<insert>truncate(size)</insert><dialog title="Insert truncate">truncate(%0)</dialog><info title="Info window"></info></function>

2010

2011

2012

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

2013

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

2014

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

2015

<param name="strstr" optional="0">strstr</param>

2016

<insert>write(strstr)</insert><dialog title="Insert write">write(%0)</dialog><info title="Info window"></info></function>

2017

2018

2019

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

2020

iterable object producing strings, typically a list of strings.

2021

There is no return value.

2022

(The name is intended to match readlines();

2023

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

2024

<param name="sequencesequence" optional="0">sequencesequence</param>

2025

<insert>writelines(sequencesequence)</insert><dialog title="Insert writelines">writelines(%0)</dialog><info title="Info window"></info></function>

2026

2027

</group>

2028

2029

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

2030

Most of these support only one or two operations.

2031

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

2032

m.name, where m is a module and name

2033

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

2034

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

2035

strictly speaking, an operation on a module object; import

2036

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

2037

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

2038

foo somewhere.)

2039

A special member of every module is __dict__.

2040

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

2041

Modifying this dictionary will actually change the module's symbol

2042

table, but direct assignment to the __dict__ attribute is not

2043

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

2044

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

2045

m.__dict__ = {}).

2046

Modules built into the interpreter are written like this:

2047

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

2048

written as <module 'os' from

2049

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

2050

Classes and Class Instances Classes and Instances

2051

See chapters 3 and 7 of the Python

2052

Reference Manual for these.

2053

Functions Function objects are created by function definitions. The only

2054

operation on a function object is to call it:

2055

func(argument-list).

2056

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

2057

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

2058

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

2059

different object types.

2060

The implementation adds two special read-only attributes:

2061

f.func_code is a function's code

2062

objectcode (see below) and f.func_globals is

2063

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

2064

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

2065

the function f was defined).

2066

Function objects also support getting and setting arbitrary

2067

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

2068

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

2069

attributes. Note that the current implementation only supports

2070

function attributes on user-defined functions. Function attributes on

2071

built-in functions may be supported in the future.

2072

Functions have another special attribute f.__dict__

2073

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

2074

support function attributes. __dict__ and func_dict can

2075

be accessed directly or set to a dictionary object. A function's

2076

dictionary cannot be deleted.

2077

Methods method

2078

Methods are functions that are called using the attribute notation.

2079

There are two flavors: built-in methods (such as append() on

2080

lists) and class instance methods. Built-in methods are described

2081

with the types that support them.

2082

The implementation adds two special read-only attributes to class

2083

instance methods: m.im_self is the object on which the

2084

method operates, and m.im_func is the function

2085

implementing the method. Calling m(arg-1,

2086

arg-2, ..., arg-n) is completely equivalent to

2087

calling m.im_func(m.im_self, arg-1,

2088

arg-2, ..., arg-n).

2089

Class instance methods are either bound or unbound,

2090

referring to whether the method was accessed through an instance or a

2091

class, respectively. When a method is unbound, its im_self

2092

attribute will be None and if called, an explicit self

2093

object must be passed as the first argument. In this case,

2094

self must be an instance of the unbound method's class (or a

2095

subclass of that class), otherwise a TypeError is raised.

2096

Like function objects, methods objects support getting

2097

arbitrary attributes. However, since method attributes are actually

2098

stored on the underlying function object (meth.im_func),

2099

setting method attributes on either bound or unbound methods is

2100

disallowed. Attempting to set a method attribute results in a

2101

TypeError being raised. In order to set a method attribute,

2102

you need to explicitly set it on the underlying function object:

2103

class C:

2104

def method(self):

2105

pass

2106

c = C()

2107

c.method.im_func.whoami = 'my name is c'

2108

See the Python Reference Manual for more

2109

information.

2110

Code Objects code

2111

Code objects are used by the implementation to represent

2112

``pseudo-compiled'' executable Python code such as a function body.

2113

They differ from function objects because they don't contain a

2114

reference to their global execution environment. Code objects are

2115

returned by the built-in compile() function and can be

2116

extracted from function objects through their func_code

2117

attribute.

2118

compile

2119

(function object attribute){func_code}

2120

A code object can be executed or evaluated by passing it (instead of a

2121

source string) to the exec statement or the built-in

2122

eval() function.

2123

exec

2124

eval

2125

See the Python Reference Manual for more

2126

information.

2127

Type Objects Type objects represent the various object types. An object's type is

2128

accessed by the built-in function type(). There are no special

2129

operations on types. The standard module types defines names

2130

for all standard built-in types.

2131

type

2132

types

2133

Types are written like this: <type 'int'>.

2134

The Null Object This object is returned by functions that don't explicitly return a

2135

value. It supports no special operations. There is exactly one null

2136

object, named None (a built-in name).

2137

It is written as None.

2138

The Ellipsis Object This object is used by extended slice notation (see the

2139

Python Reference Manual). It supports no

2140

special operations. There is exactly one ellipsis object, named

2141

Ellipsis (a built-in name).

2142

It is written as Ellipsis.

2143

Boolean Values

2144

Boolean values are the two constant objects False and

2145

True. They are used to represent truth values (although other

2146

values can also be considered false or true). In numeric contexts

2147

(for example when used as the argument to an arithmetic operator),

2148

they behave like the integers 0 and 1, respectively. The built-in

2149

function bool() can be used to cast any value to a Boolean,

2150

if the value can be interpreted as a truth value (see section Truth

2151

Value Testing above).

2152

They are written as False and True, respectively.

2153

</description>

2154

</group>

2155

2156

</group>

2157

</group>

2158

2159

</group>

2160

</group>

2161

2162

2163

<description>Access system-specific parameters and functions.

2164

This module provides access to some variables used or maintained by the

2165

interpreter and to functions that interact strongly with the interpreter.

2166

It is always available.

2167

{argv}

2168

The list of command line arguments passed to a Python script.

2169

argv[0] is the script name (it is operating system dependent

2170

whether this is a full pathname or not). If the command was

2171

executed using the -c command line option to the

2172

interpreter, argv[0] is set to the string '-c'. If no

2173

script name was passed to the Python interpreter, argv has

2174

zero length.

2175

{byteorder}

2176

An indicator of the native byte order. This will have the value

2177

'big' on big-endian (most-signigicant byte first) platforms,

2178

and 'little' on little-endian (least-significant byte first)

2179

platforms.

2180

New in version 2.0

2181

{builtin_module_names}

2182

A tuple of strings giving the names of all modules that are compiled

2183

into this Python interpreter. (This information is not available in

2184

any other way --- modules.keys() only lists the imported

2185

modules.)

2186

{copyright}

2187

A string containing the copyright pertaining to the Python

2188

interpreter.

2189

{dllhandle}

2190

Integer specifying the handle of the Python DLL.

2191

Availability: Windows.

2192

</description>

2193

2194

<description>If value is not None, this function prints it to

2195

sys.stdout, and saves it in __builtin__._.

2196

sys.displayhook is called on the result of evaluating an

2197

expression entered in an interactive Python session. The display of

2198

these values can be customized by assigning another one-argument

2199

function to sys.displayhook.</description>

2200

<param name="value" optional="0">value</param>

2201

<insert>displayhook(value)</insert><dialog title="Insert displayhook">displayhook(%0)</dialog><info title="Info window"></info></function>

2202

2203

2204

<description>This function prints out a given traceback and exception to

2205

sys.stderr.

2206

When an exception is raised and uncaught, the interpreter calls

2207

sys.excepthook with three arguments, the exception class,

2208

exception instance, and a traceback object. In an interactive

2209

session this happens just before control is returned to the prompt;

2210

in a Python program this happens just before the program exits. The

2211

handling of such top-level exceptions can be customized by assigning

2212

another three-argument function to sys.excepthook.</description>

2213

<param name="type" optional="0">type</param><param name="value" optional="0">value</param><param name="traceback" optional="0">traceback</param>

2214

<insert>excepthook(type, value, traceback)</insert><dialog title="Insert excepthook">excepthook(%0, %1, %2)</dialog><info title="Info window"></info></function>

2215

2216

2217

<description>This function returns a tuple of three values that give information

2218

about the exception that is currently being handled. The

2219

information returned is specific both to the current thread and to

2220

the current stack frame. If the current stack frame is not handling

2221

an exception, the information is taken from the calling stack frame,

2222

or its caller, and so on until a stack frame is found that is

2223

handling an exception. Here, ``handling an exception'' is defined

2224

as ``executing or having executed an except clause.'' For any stack

2225

frame, only information about the most recently handled exception is

2226

accessible.

2227

If no exception is being handled anywhere on the stack, a tuple

2228

containing three None values is returned. Otherwise, the

2229

values returned are (type, value,

2230

traceback). Their meaning is: type gets the exception

2231

type of the exception being handled (a class object);

2232

value gets the exception parameter (its associated value

2233

or the second argument to raise, which is always a class

2234

instance if the exception type is a class object); traceback

2235

gets a traceback object (see the Reference Manual) which

2236

encapsulates the call stack at the point where the exception

2237

originally occurred. traceback

2238

If exc_clear() is called, this function will return three

2239

None values until either another exception is raised in the

2240

current thread or the execution stack returns to a frame where

2241

another exception is being handled.

2242

Assigning the traceback return value to a

2243

local variable in a function that is handling an exception will

2244

cause a circular reference. This will prevent anything referenced

2245

by a local variable in the same function or by the traceback from

2246

being garbage collected. Since most functions don't need access to

2247

the traceback, the best solution is to use something like

2248

exctype, value = sys.exc_info()[:2] to extract only the

2249

exception type and value. If you do need the traceback, make sure

2250

to delete it after use (best done with a try

2251

... finally statement) or to call exc_info() in

2252

a function that does not itself handle an exception. Beginning

2253

with Python 2.2, such cycles are automatically reclaimed when garbage

2254

collection is enabled and they become unreachable, but it remains more

2255

efficient to avoid creating cycles.</description>

2256

2257

2258

2259

2260

<description>This function clears all information relating to the current or last

2261

exception that occured in the current thread. After calling this

2262

function, exc_info() will return three None values until

2263

another exception is raised in the current thread or the execution stack

2264

returns to a frame where another exception is being handled.

2265

This function is only needed in only a few obscure situations. These

2266

include logging and error handling systems that report information on the

2267

last or current exception. This function can also be used to try to free

2268

resources and trigger object finalization, though no guarantee is made as

2269

to what objects will be freed, if any.

2270

New in version 2.3</description>

2271

2272

<insert>exc_clear()</insert><dialog title="Insert exc_clear">exc_clear()</dialog><info title="Info window"></info></function>

2273

2274

2275

<description>Exit from Python. This is implemented by raising the

2276

SystemExit exception, so cleanup actions specified by

2277

finally clauses of try statements are honored, and it is

2278

possible to intercept the exit attempt at an outer level. The

2279

optional argument arg can be an integer giving the exit status

2280

(defaulting to zero), or another type of object. If it is an

2281

integer, zero is considered ``successful termination'' and any

2282

nonzero value is considered ``abnormal termination'' by shells and

2283

the like. Most systems require it to be in the range 0-127, and

2284

produce undefined results otherwise. Some systems have a convention

2285

for assigning specific meanings to specific exit codes, but these

2286

are generally underdeveloped; programs generally use 2 for

2287

command line syntax errors and 1 for all other kind of errors. If

2288

another type of object is passed, None is equivalent to

2289

passing zero, and any other object is printed to sys.stderr

2290

and results in an exit code of 1. In particular,

2291

sys.exit("some error message") is a quick way to exit a

2292

program when an error occurs.</description>

2293

2294

2295

2296

2297

<description>Return the interpreter's ``check interval'';

2298

see setcheckinterval().

2299

New in version 2.3</description>

2300

2301

<insert>getcheckinterval()</insert><dialog title="Insert getcheckinterval">getcheckinterval()</dialog><info title="Info window"></info></function>

2302

2303

2304

<description>Return the name of the current default string encoding used by the

2305

Unicode implementation.

2306

New in version 2.0</description>

2307

2308

<insert>getdefaultencoding()</insert><dialog title="Insert getdefaultencoding">getdefaultencoding()</dialog><info title="Info window"></info></function>

2309

2310

2311

<description>Return the current value of the flags that are used for

2312

dlopen() calls. The flag constants are defined in the

2313

dl and DLFCN modules.

2314

Availability: .

2315

New in version 2.2</description>

2316

2317

<insert>getdlopenflags()</insert><dialog title="Insert getdlopenflags">getdlopenflags()</dialog><info title="Info window"></info></function>

2318

2319

2320

<description>Return the name of the encoding used to convert Unicode filenames

2321

into system file names, or None if the system default encoding

2322

is used. The result value depends on the operating system:

2323

On Windows 9x, the encoding is ``mbcs''.

2324

On Mac OS X, the encoding is ``utf-8''.

2325

On Unix, the encoding is the user's preference according to the result of nl_langinfo(CODESET), or None if

2326

the nl_langinfo(CODESET) failed.

2327

On Windows NT+, file names are Unicode natively, so no conversion

2328

is performed.

2329

New in version 2.3</description>

2330

2331

<insert>getfilesystemencoding()</insert><dialog title="Insert getfilesystemencoding">getfilesystemencoding()</dialog><info title="Info window"></info></function>

2332

2333

2334

<description>Return the reference count of the object. The count returned

2335

is generally one higher than you might expect, because it includes

2336

the (temporary) reference as an argument to

2337

getrefcount().</description>

2338

<param name="objectobject" optional="0">objectobject</param>

2339

<insert>getrefcount(objectobject)</insert><dialog title="Insert getrefcount">getrefcount(%0)</dialog><info title="Info window"></info></function>

2340

2341

2342

<description>Return the current value of the recursion limit, the maximum depth

2343

of the Python interpreter stack. This limit prevents infinite

2344

recursion from causing an overflow of the C stack and crashing

2345

Python. It can be set by setrecursionlimit().</description>

2346

2347

<insert>getrecursionlimit()</insert><dialog title="Insert getrecursionlimit">getrecursionlimit()</dialog><info title="Info window"></info></function>

2348

2349

2350

<description>Return a frame object from the call stack. If optional integer

2351

depth is given, return the frame object that many calls below

2352

the top of the stack. If that is deeper than the call stack,

2353

ValueError is raised. The default for depth is

2354

zero, returning the frame at the top of the call stack.

2355

This function should be used for internal and specialized purposes

2356

only.</description>

2357

<param name="depth" optional="0">depth</param>

2358

<insert>_getframe(depth)</insert><dialog title="Insert _getframe">_getframe(%0)</dialog><info title="Info window"></info></function>

2359

2360

2361

<description>Return a tuple containing five components, describing the Windows version currently running. The elements are major, minor, build, platform, and text. text contains

2362

a string while all other values are integers.

2363

platform may be one of the following values:

2364

{}{ 0.7in 0.65in}

2365

[0 (VER_PLATFORM_WIN32s)]

2366

Win32s on Windows 3.1.

2367

[1 (VER_PLATFORM_WIN32_WINDOWS)] Windows 95/98/ME

2368

[2 (VER_PLATFORM_WIN32_NT)] Windows NT/2000/XP

2369

[3 (VER_PLATFORM_WIN32_CE)] Windows CE.

2370

This function wraps the Win32 GetVersionEx() function;

2371

see the Microsoft Documentation for more information about these

2372

fields.

2373

Availability: Windows.

2374

New in version 2.3</description>

2375

2376

<insert>getwindowsversion()</insert><dialog title="Insert getwindowsversion">getwindowsversion()</dialog><info title="Info window"></info></function>

2377

2378

2379

<description>Set the interpreter's ``check interval''. This integer value

2380

determines how often the interpreter checks for periodic things such

2381

as thread switches and signal handlers. The default is 100,

2382

meaning the check is performed every 100 Python virtual instructions.

2383

Setting it to a larger value may increase performance for programs

2384

using threads. Setting it to a value <= 0 checks every

2385

virtual instruction, maximizing responsiveness as well as overhead.</description>

2386

<param name="intervalinterval" optional="0">intervalinterval</param>

2387

<insert>setcheckinterval(intervalinterval)</insert><dialog title="Insert setcheckinterval">setcheckinterval(%0)</dialog><info title="Info window"></info></function>

2388

2389

2390

<description>Set the current default string encoding used by the Unicode

2391

implementation. If name does not match any available

2392

encoding, LookupError is raised. This function is only

2393

intended to be used by the site module implementation

2394

and, where needed, by sitecustomize. Once used by the

2395

site module, it is removed from the sys

2396

module's namespace.

2397

% Note that site is not imported if

2398

% the -S option is passed to the interpreter, in which

2399

% case this function will remain available.

2400

New in version 2.0</description>

2401

<param name="namename" optional="0">namename</param>

2402

<insert>setdefaultencoding(namename)</insert><dialog title="Insert setdefaultencoding">setdefaultencoding(%0)</dialog><info title="Info window"></info></function>

2403

2404

2405

<description>Set the flags used by the interpreter for dlopen()

2406

calls, such as when the interpreter loads extension modules. Among

2407

other things, this will enable a lazy resolving of symbols when

2408

importing a module, if called as sys.setdlopenflags(0). To

2409

share symbols across extension modules, call as

2410

sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL). Symbolic

2411

names for the flag modules can be either found in the dl

2412

module, or in the DLFCN module. If DLFCN is not

2413

available, it can be generated from /usr/include/dlfcn.h

2414

using the h2py script.

2415

Availability: .

2416

New in version 2.2</description>

2417

2418

<insert>setdlopenflags(nn)</insert><dialog title="Insert setdlopenflags">setdlopenflags(%0)</dialog><info title="Info window"></info></function>

2419

2420

2421

<description>Set the system's profile function,</description>

2422

<param name="profilefuncprofilefunc" optional="0">profilefuncprofilefunc</param>

2423

<insert>setprofile(profilefuncprofilefunc)</insert><dialog title="Insert setprofile">setprofile(%0)</dialog><info title="Info window"></info></function>

2424

2425

2426

<description>Set the maximum depth of the Python interpreter stack to

2427

limit. This limit prevents infinite recursion from causing an

2428

overflow of the C stack and crashing Python.

2429

The highest possible limit is platform-dependent. A user may need

2430

to set the limit higher when she has a program that requires deep

2431

recursion and a platform that supports a higher limit. This should

2432

be done with care, because a too-high limit can lead to a crash.</description>

2433

<param name="limitlimit" optional="0">limitlimit</param>

2434

<insert>setrecursionlimit(limitlimit)</insert><dialog title="Insert setrecursionlimit">setrecursionlimit(%0)</dialog><info title="Info window"></info></function>

2435

2436

2437

<description>Set the system's trace function,</description>

2438

<param name="tracefunctracefunc" optional="0">tracefunctracefunc</param>

2439

<insert>settrace(tracefunctracefunc)</insert><dialog title="Insert settrace">settrace(%0)</dialog><info title="Info window"></info></function>

2440

2441

</group>

2442

2443

<description>Interface to the cycle-detecting garbage collector.

2444

The gc module is only available if the interpreter was built

2445

with the optional cyclic garbage detector (enabled by default). If

2446

this was not enabled, an ImportError is raised by attempts

2447

to import this module.

2448

This module provides an interface to the optional garbage collector. It

2449

provides the ability to disable the collector, tune the collection

2450

frequency, and set debugging options. It also provides access to

2451

unreachable objects that the collector found but cannot free. Since the

2452

collector supplements the reference counting already used in Python, you

2453

can disable the collector if you are sure your program does not create

2454

reference cycles. Automatic collection can be disabled by calling

2455

gc.disable(). To debug a leaking program call

2456

gc.set_debug(gc.DEBUG_LEAK).

2457

The gc module provides the following functions:

2458

</description>

2459

2460

<description>Enable automatic garbage collection.</description>

2461

2462

<insert>enable()</insert><dialog title="Insert enable">enable()</dialog><info title="Info window"></info></function>

2463

2464

2465

<description>Disable automatic garbage collection.</description>

2466

2467

<insert>disable()</insert><dialog title="Insert disable">disable()</dialog><info title="Info window"></info></function>

2468

2469

2470

<description>Returns true if automatic collection is enabled.</description>

2471

2472

<insert>isenabled()</insert><dialog title="Insert isenabled">isenabled()</dialog><info title="Info window"></info></function>

2473

2474

2475

<description>Run a full collection. All generations are examined and the

2476

number of unreachable objects found is returned.</description>

2477

2478

<insert>collect()</insert><dialog title="Insert collect">collect()</dialog><info title="Info window"></info></function>

2479

2480

2481

<description>Set the garbage collection debugging flags.

2482

Debugging information will be written to sys.stderr. See below

2483

for a list of debugging flags which can be combined using bit

2484

operations to control debugging.</description>

2485

<param name="flagsflags" optional="0">flagsflags</param>

2486

<insert>set_debug(flagsflags)</insert><dialog title="Insert set_debug">set_debug(%0)</dialog><info title="Info window"></info></function>

2487

2488

2489

<description>Return the debugging flags currently set.</description>

2490

2491

<insert>get_debug()</insert><dialog title="Insert get_debug">get_debug()</dialog><info title="Info window"></info></function>

2492

2493

2494

<description>Returns a list of all objects tracked by the collector, excluding the

2495

list returned.

2496

New in version 2.2</description>

2497

2498

<insert>get_objects()</insert><dialog title="Insert get_objects">get_objects()</dialog><info title="Info window"></info></function>

2499

2500

2501

<description>Set the garbage collection thresholds (the collection frequency).

2502

Setting threshold0 to zero disables collection.

2503

The GC classifies objects into three generations depending on how many

2504

collection sweeps they have survived. New objects are placed in the

2505

youngest generation (generation 0). If an object survives a

2506

collection it is moved into the next older generation. Since

2507

generation 2 is the oldest generation, objects in that

2508

generation remain there after a collection. In order to decide when

2509

to run, the collector keeps track of the number object allocations and

2510

deallocations since the last collection. When the number of

2511

allocations minus the number of deallocations exceeds

2512

threshold0, collection starts. Initially only generation

2513

0 is examined. If generation 0 has been examined more

2514

than threshold1 times since generation 1 has been

2515

examined, then generation 1 is examined as well. Similarly,

2516

threshold2 controls the number of collections of generation

2517

1 before collecting generation 2.</description>

2518

<param name="threshold0" optional="0">threshold0</param><param name="threshold1" optional="1">threshold1</param><param name="threshold2" optional="1">threshold2</param>

2519

<insert>set_threshold(threshold0, [threshold1], [threshold2])</insert><dialog title="Insert set_threshold">set_threshold(%0, %1, %2)</dialog><info title="Info window"></info></function>

2520

2521

2522

<description>Return the current collection thresholds as a tuple of

2523

(threshold0, threshold1, threshold2).</description>

2524

2525

<insert>get_threshold()</insert><dialog title="Insert get_threshold">get_threshold()</dialog><info title="Info window"></info></function>

2526

2527

2528

<description>Return the list of objects that directly refer to any of objs. This

2529

function will only locate those containers which support garbage

2530

collection; extension types which do refer to other objects but do not

2531

support garbage collection will not be found.

2532

Note that objects which have already been dereferenced, but which live

2533

in cycles and have not yet been collected by the garbage collector can

2534

be listed among the resulting referrers. To get only currently live

2535

objects, call collect() before calling

2536

get_referrers().

2537

Care must be taken when using objects returned by

2538

get_referrers() because some of them could still be under

2539

construction and hence in a temporarily invalid state. Avoid using

2540

get_referrers() for any purpose other than debugging.

2541

New in version 2.2</description>

2542

2543

<insert>get_referrers(*objs*objs)</insert><dialog title="Insert get_referrers">get_referrers(%0)</dialog><info title="Info window"></info></function>

2544

2545

2546

<description>Return a list of objects directly referred to by any of the arguments.

2547

The referents returned are those objects visited by the arguments'

2548

C-level tp_traverse methods (if any), and may not be all

2549

objects actually directly reachable. tp_traverse methods

2550

are supported only by objects that support garbage collection, and are

2551

only required to visit objects that may be involved in a cycle. So,

2552

for example, if an integer is directly reachable from an argument, that

2553

integer object may or may not appear in the result list.

2554

New in version 2.3</description>

2555

2556

<insert>get_referents(*objs*objs)</insert><dialog title="Insert get_referents">get_referents(%0)</dialog><info title="Info window"></info></function>

2557

2558

</group>

2559

2560

<description>Support for weak references and weak dictionaries.

2561

New in version 2.1

2562

The weakref module allows the Python programmer to create

2563

weak references to objects.

2564

In the following, the term referent means the

2565

object which is referred to by a weak reference.

2566

A weak reference to an object is not enough to keep the object alive:

2567

when the only remaining references to a referent are weak references,

2568

garbage collection is free to destroy the referent and reuse its memory

2569

for something else. A primary use for weak references is to implement

2570

caches or mappings holding large objects, where it's desired that a

2571

large object not be kept alive solely because it appears in a cache or

2572

mapping. For example, if you have a number of large binary image objects,

2573

you may wish to associate a name with each. If you used a Python

2574

dictionary to map names to images, or images to names, the image objects

2575

would remain alive just because they appeared as values or keys in the

2576

dictionaries. The WeakKeyDictionary and

2577

WeakValueDictionary classes supplied by the weakref

2578

module are an alternative, using weak references to construct mappings

2579

that don't keep objects alive solely because they appear in the mapping

2580

objects. If, for example, an image object is a value in a

2581

WeakValueDictionary, then when the last remaining

2582

references to that image object are the weak references held by weak

2583

mappings, garbage collection can reclaim the object, and its corresponding

2584

entries in weak mappings are simply deleted.

2585

WeakKeyDictionary and WeakValueDictionary use weak

2586

references in their implementation, setting up callback functions on

2587

the weak references that notify the weak dictionaries when a key or value

2588

has been reclaimed by garbage collection. Most programs should find that

2589

using one of these weak dictionary types is all they need -- it's

2590

not usually necessary to create your own weak references directly. The

2591

low-level machinery used by the weak dictionary implementations is exposed

2592

by the weakref module for the benefit of advanced uses.

2593

Not all objects can be weakly referenced; those objects which can

2594

include class instances, functions written in Python (but not in C),

2595

and methods (both bound and unbound). Extension types can easily

2596

be made to support weak references; see section weakref-extension,

2597

``Weak References in Extension Types,'' for more information.

2598

</description>

2599

2600

<description>Return a weak reference to object. The original object can be

2601

retrieved by calling the reference object if the referent is still

2602

alive; if the referent is no longer alive, calling the reference

2603

object will cause None to be returned. If callback is

2604

provided, it will be called when the object is about to be

2605

finalized; the weak reference object will be passed as the only

2606

parameter to the callback; the referent will no longer be available.

2607

It is allowable for many weak references to be constructed for the

2608

same object. Callbacks registered for each weak reference will be

2609

called from the most recently registered callback to the oldest

2610

registered callback.

2611

Exceptions raised by the callback will be noted on the standard

2612

error output, but cannot be propagated; they are handled in exactly

2613

the same way as exceptions raised from an object's

2614

__del__() method.

2615

Weak references are hashable if the object is hashable. They

2616

will maintain their hash value even after the object was

2617

deleted. If hash() is called the first time only after

2618

the object was deleted, the call will raise

2619

TypeError.

2620

Weak references support tests for equality, but not ordering. If

2621

the referents are still alive, two references have the same

2622

equality relationship as their referents (regardless of the

2623

callback). If either referent has been deleted, the

2624

references are equal only if the reference objects are the same

2625

object.</description>

2626

<param name="object" optional="0">object</param><param name="callback" optional="1">callback</param>

2627

<insert>ref(object, [callback])</insert><dialog title="Insert ref">ref(%0, %1)</dialog><info title="Info window"></info></function>

2628

2629

2630

<description>Return a proxy to object which uses a weak reference. This

2631

supports use of the proxy in most contexts instead of requiring the

2632

explicit dereferencing used with weak reference objects. The

2633

returned object will have a type of either ProxyType or

2634

CallableProxyType, depending on whether object is

2635

callable. Proxy objects are not hashable regardless of the

2636

referent; this avoids a number of problems related to their

2637

fundamentally mutable nature, and prevent their use as dictionary

2638

keys. callback is the same as the parameter of the same name

2639

to the ref() function.</description>

2640

<param name="object" optional="0">object</param><param name="callback" optional="1">callback</param>

2641

<insert>proxy(object, [callback])</insert><dialog title="Insert proxy">proxy(%0, %1)</dialog><info title="Info window"></info></function>

2642

2643

2644

<description>Return the number of weak references and proxies which refer to

2645

object.</description>

2646

<param name="objectobject" optional="0">objectobject</param>

2647

<insert>getweakrefcount(objectobject)</insert><dialog title="Insert getweakrefcount">getweakrefcount(%0)</dialog><info title="Info window"></info></function>

2648

2649

2650

<description>Return a list of all weak reference and proxy objects which refer to

2651

object.</description>

2652

<param name="objectobject" optional="0">objectobject</param>

2653

<insert>getweakrefs(objectobject)</insert><dialog title="Insert getweakrefs">getweakrefs(%0)</dialog><info title="Info window"></info></function>

2654

2655

2656

<description>Mapping class that references keys weakly. Entries in the

2657

dictionary will be discarded when there is no longer a strong

2658

reference to the key. This can be used to associate additional data

2659

with an object owned by other parts of an application without adding

2660

attributes to those objects. This can be especially useful with

2661

objects that override attribute accesses.

2662

Caution: Because a WeakKeyDictionary is built on top

2663

of a Python dictionary, it must not change size when iterating

2664

over it. This can be difficult to ensure for a

2665

WeakKeyDictionary because actions performed by the

2666

program during iteration may cause items in the dictionary

2667

to vanish "by magic" (as a side effect of garbage collection).</description>

2668

2669

<insert>WeakKeyDictionary(dict)</insert><dialog title="Insert WeakKeyDictionary">WeakKeyDictionary(%0)</dialog><info title="Info window"></info></function>

2670

2671

2672

<description>Mapping class that references values weakly. Entries in the

2673

dictionary will be discarded when no strong reference to the value

2674

exists any more.

2675

Caution: Because a WeakValueDictionary is built on top

2676

of a Python dictionary, it must not change size when iterating

2677

over it. This can be difficult to ensure for a

2678

WeakValueDictionary because actions performed by the

2679

program during iteration may cause items in the dictionary

2680

to vanish "by magic" (as a side effect of garbage collection).</description>

2681

2682

<insert>WeakValueDictionary(dict)</insert><dialog title="Insert WeakValueDictionary">WeakValueDictionary(%0)</dialog><info title="Info window"></info></function>

2683

2684

2685

<description>Weak reference objects have no attributes or methods, but do allow the

2686

referent to be obtained, if it still exists, by calling it:

2687

>>> import weakref

2688

>>> class Object:

2689

... pass

2690

...

2691

>>> o = Object()

2692

>>> r = weakref.ref(o)

2693

>>> o2 = r()

2694

>>> o is o2

2695

True

2696

If the referent no longer exists, calling the reference object returns

2697

None:

2698

>>> del o, o2

2699

>>> print r()

2700

None

2701

Testing that a weak reference object is still live should be done

2702

using the expression ref() is not None. Normally,

2703

application code that needs to use a reference object should follow

2704

this pattern:

2705

# r is a weak reference object

2706

o = r()

2707

if o is None:

2708

# referent has been garbage collected

2709

print "Object has been allocated; can't frobnicate."

2710

else:

2711

print "Object is still live!"

2712

o.do_something_useful()

2713

Using a separate test for ``liveness'' creates race conditions in

2714

threaded applications; another thread can cause a weak reference to

2715

become invalidated before the weak reference is called; the

2716

idiom shown above is safe in threaded applications as well as

2717

single-threaded applications.

2718

</description>

2719

</group>

2720

2721

<description>This simple example shows how an application can use objects IDs to

2722

retrieve objects that it has seen before. The IDs of the objects can

2723

then be used in other data structures without forcing the objects to

2724

remain alive, but the objects can still be retrieved by ID if they

2725

do.

2726

% Example contributed by Tim Peters <tim_one@msn.com>.

2727

import weakref

2728

_id2obj_dict = weakref.WeakValueDictionary()

2729

def remember(obj):

2730

oid = id(obj)

2731

_id2obj_dict[oid] = obj

2732

return oid

2733

def id2obj(oid):

2734

return _id2obj_dict[oid]

2735

</description>

2736

</group>

2737

2738

</group>

2739

</group>

2740

2741

<description>Unix

2742

Provide control for floating point exception handling.

2743

Most computers carry out floating point operations</description>

2744

2745

<description>Turn on the generation of SIGFPE,

2746

and set up an appropriate signal handler.</description>

2747

2748

<insert>turnon_sigfpe()</insert><dialog title="Insert turnon_sigfpe">turnon_sigfpe()</dialog><info title="Info window"></info></function>

2749

2750

2751

<description>Reset default handling of floating point exceptions.</description>

2752

2753

<insert>turnoff_sigfpe()</insert><dialog title="Insert turnoff_sigfpe">turnoff_sigfpe()</dialog><info title="Info window"></info></function>

2754

2755

2756

<description>The following example demonstrates how to start up and test operation of

2757

the fpectl module.

2758

>>> import fpectl

2759

>>> import fpetest

2760

>>> fpectl.turnon_sigfpe()

2761

>>> fpetest.test()

2762

overflow PASS

2763

FloatingPointError: Overflow

2764

div by 0 PASS

2765

FloatingPointError: Division by zero

2766

[ more output from test elided ]

2767

>>> import math

2768

>>> math.exp(1000)

2769

Traceback (most recent call last):

2770

File "<stdin>", line 1, in ?

2771

FloatingPointError: in math_1

2772

</description>

2773

</group>

2774

2775

</group>

2776

</group>

2777

2778

<description>Register and execute cleanup functions.

2779

New in version 2.0

2780

The atexit module defines a single function to register

2781

cleanup functions. Functions thus registered are automatically

2782

executed upon normal interpreter termination.

2783

Note: the functions registered via this module are not called when the program is killed by a

2784

signal, when a Python fatal internal error is detected, or when

2785

os._exit() is called.

2786

This is an alternate interface to the functionality provided by the

2787

sys.exitfunc variable.

2788

(in sys){exitfunc}

2789

Note: This module is unlikely to work correctly when used with other code

2790

that sets sys.exitfunc. In particular, other core Python modules are

2791

free to use atexit without the programmer's knowledge. Authors who

2792

use sys.exitfunc should convert their code to use

2793

atexit instead. The simplest way to convert code that sets

2794

sys.exitfunc is to import atexit and register the function

2795

that had been bound to sys.exitfunc.

2796

</description>

2797

2798

<description>Register func as a function to be executed at termination. Any

2799

optional arguments that are to be passed to func must be passed

2800

as arguments to register().

2801

At normal program termination (for instance, if

2802

sys.exit() is called or the main module's execution

2803

completes), all functions registered are called in last in, first out

2804

order. The assumption is that lower level modules will normally be

2805

imported before higher level modules and thus must be cleaned up

2806

later.</description>

2807

<param name="func" optional="0">func</param><param name="*args" optional="1">*args</param><param name="**kargs" optional="1">**kargs</param>

2808

<insert>register(func, [*args], [**kargs])</insert><dialog title="Insert register">register(%0, %1, %2)</dialog><info title="Info window"></info></function>

2809

2810

2811

</group>

2812

</group>

2813

2814

</group>

2815

2816

<description>Class wrapper for dictionary objects.

2817

This module is available for backward compatibility only. If

2818

you are writing code that does not need to work with versions of

2819

Python earlier than Python 2.2, please consider subclassing directly

2820

from the built-in dict type.

2821

This module defines a class that acts as a wrapper around

2822

dictionary objects. It is a useful base class for

2823

your own dictionary-like classes, which can inherit from

2824

them and override existing methods or add new ones. In this way one

2825

can add new behaviors to dictionaries.

2826

The module also defines a mixin defining all dictionary methods for

2827

classes that already have a minimum mapping interface. This greatly

2828

simplifies writing classes that need to be substitutable for

2829

dictionaries (such as the shelve module).

2830

The UserDict module defines the UserDict class

2831

and DictMixin:

2832

</description>

2833

2834

<description>Class that simulates a dictionary. The instance's

2835

contents are kept in a regular dictionary, which is accessible via the

2836

data attribute of UserDict instances. If

2837

initialdata is provided, data is initialized with its

2838

contents; note that a reference to initialdata will not be kept, allowing it be used for other purposes.</description>

2839

<param name="initialdata" optional="0">initialdata</param>

2840

<insert>UserDict(initialdata)</insert><dialog title="Insert UserDict">UserDict(%0)</dialog><info title="Info window"></info></function>

2841

2842

2843

<description>Mixin defining all dictionary methods for classes that already have

2844

a minimum dictionary interface including __getitem__(),

2845

__setitem__(), __delitem__(), and keys().

2846

This mixin should be used as a superclass. Adding each of the

2847

above methods adds progressively more functionality. For instance,

2848

defining all but __delitem__ will preclude only pop

2849

and popitem from the full interface.

2850

In addition to the four base methods, progessively more efficiency

2851

comes with defining __contains__(), __iter__(), and

2852

iteritems().

2853

Since the mixin has no knowledge of the subclass constructor, it

2854

does not define __init__() or copy().</description>

2855

2856

<insert>DictMixin()</insert><dialog title="Insert DictMixin">DictMixin()</dialog><info title="Info window"></info></function>

2857

2858

2859

<description>Class that simulates a list. The instance's

2860

contents are kept in a regular list, which is accessible via the

2861

data attribute of UserList instances. The instance's

2862

contents are initially set to a copy of list, defaulting to the

2863

empty list []. list can be either a regular Python list,

2864

or an instance of UserList (or a subclass).</description>

2865

2866

<insert>UserList(list)</insert><dialog title="Insert UserList">UserList(%0)</dialog><info title="Info window"></info></function>

2867

2868

2869

<description>Class that simulates a string or a Unicode string

2870

object. The instance's content is kept in a regular string or Unicode

2871

string object, which is accessible via the data attribute of

2872

UserString instances. The instance's contents are initially

2873

set to a copy of sequence. sequence can be either a

2874

regular Python string or Unicode string, an instance of

2875

UserString (or a subclass) or an arbitrary sequence which can

2876

be converted into a string using the built-in str() function.</description>

2877

<param name="sequence" optional="0">sequence</param>

2878

<insert>UserString(sequence)</insert><dialog title="Insert UserString">UserString(%0)</dialog><info title="Info window"></info></function>

2879

2880

2881

<description>This class is derived from the UserString above and redefines

2882

strings to be mutable. Mutable strings can't be used as

2883

dictionary keys, because dictionaries require immutable objects as

2884

keys. The main intention of this class is to serve as an educational

2885

example for inheritance and necessity to remove (override) the

2886

__hash__() method in order to trap attempts to use a

2887

mutable object as dictionary key, which would be otherwise very

2888

error prone and hard to track down.</description>

2889

<param name="sequence" optional="0">sequence</param>

2890

<insert>MutableString(sequence)</insert><dialog title="Insert MutableString">MutableString(%0)</dialog><info title="Info window"></info></function>

2891

2892

</group>

2893

2894

<description>All Python's standard operators as built-in functions.

2895

The operator module exports a set of functions implemented in C

2896

corresponding to the intrinsic operators of Python. For example,

2897

operator.add(x, y) is equivalent to the expression x+y. The

2898

function names are those used for special class methods; variants without

2899

leading and trailing __ are also provided for convenience.

2900

The functions fall into categories that perform object comparisons,

2901

logical operations, mathematical operations, sequence operations, and

2902

abstract type tests.

2903

The object comparison functions are useful for all objects, and are

2904

named after the rich comparison operators they support:

2905

</description>

2906

2907

<description>le{a, b}

2908

eq{a, b}

2909

ne{a, b}

2910

ge{a, b}

2911

gt{a, b}

2912

__lt__{a, b}

2913

__le__{a, b}

2914

__eq__{a, b}

2915

__ne__{a, b}

2916

__ge__{a, b}

2917

__gt__{a, b}

2918

Perform ``rich comparisons'' between a and b. Specifically,

2919

lt(a, b) is equivalent to a < b,

2920

le(a, b) is equivalent to a <= b,

2921

eq(a, b) is equivalent to a == b,

2922

ne(a, b) is equivalent to a != b,

2923

gt(a, b) is equivalent to a > b

2924

and

2925

ge(a, b) is equivalent to a >= b.

2926

Note that unlike the built-in cmp(), these functions can

2927

return any value, which may or may not be interpretable as a Boolean

2928

value. See the Python Reference Manual

2929

for more informations about rich comparisons.

2930

New in version 2.2</description>

2931

2932

2933

2934

2935

<description>__not__{o}

2936

Return the outcome of not o. (Note that there is no

2937

__not__() method for object instances; only the interpreter

2938

core defines this operation. The result is affected by the

2939

__nonzero__() and __len__() methods.)</description>

2940

2941

2942

2943

2944

<description>Return True if o is true, and False

2945

otherwise. This is equivalent to using the bool

2946

constructor.</description>

2947

2948

<insert>truth(oo)</insert><dialog title="Insert truth">truth(%0)</dialog><info title="Info window"></info></function>

2949

2950

2951

<description>Return a is b. Tests object identity.

2952

New in version 2.3</description>

2953

2954

2955

2956

2957

<description>Return a is not b. Tests object identity.

2958

New in version 2.3</description>

2959

2960

2961

2962

2963

<description>__abs__{o}

2964

Return the absolute value of o.</description>

2965

2966

2967

2968

2969

<description>__add__{a, b}

2970

Return a + b, for a and b numbers.</description>

2971

2972

2973

2974

2975

<description>__and__{a, b}

2976

Return the bitwise and of a and b.</description>

2977

2978

2979

2980

2981

<description>__div__{a, b}

2982

Return a / b when __future__.division is not

2983

in effect. This is also known as ``classic'' division.</description>

2984

2985

2986

2987

2988

<description>__floordiv__{a, b}

2989

Return a // b.

2990

New in version 2.2</description>

2991

2992

<insert>floordiv(a, b b)</insert><dialog title="Insert floordiv">floordiv(%0, %1)</dialog><info title="Info window"></info></function>

2993

2994

2995

<description>invert{o}

2996

__inv__{o}

2997

__invert__{o}

2998

Return the bitwise inverse of the number o. This is equivalent

2999

to o. The names invert() and

3000

__invert__() were added in Python 2.0.</description>

3001

3002

3003

3004

3005

<description>__lshift__{a, b}

3006

Return a shifted left by b.</description>

3007

3008

<insert>lshift(a, b b)</insert><dialog title="Insert lshift">lshift(%0, %1)</dialog><info title="Info window"></info></function>

3009

3010

3011

<description>__mod__{a, b}

3012

Return a % b.</description>

3013

3014

3015

3016

3017

<description>__mul__{a, b}

3018

Return a * b, for a and b numbers.</description>

3019

3020

3021

3022

3023

<description>__neg__{o}

3024

Return o negated.</description>

3025

3026

3027

3028

3029

<description>__or__{a, b}

3030

Return the bitwise or of a and b.</description>

3031

3032

3033

3034

3035

<description>__pos__{o}

3036

Return o positive.</description>

3037

3038

3039

3040

3041

<description>__pow__{a, b}

3042

Return a ** b, for a and b numbers.

3043

New in version 2.3</description>

3044

3045

3046

3047

3048

<description>__rshift__{a, b}

3049

Return a shifted right by b.</description>

3050

3051

<insert>rshift(a, b b)</insert><dialog title="Insert rshift">rshift(%0, %1)</dialog><info title="Info window"></info></function>

3052

3053

3054

<description>__sub__{a, b}

3055

Return a - b.</description>

3056

3057

3058

3059

3060

<description>__truediv__{a, b}

3061

Return a / b when __future__.division is in

3062

effect. This is also known as division.

3063

New in version 2.2</description>

3064

3065

<insert>truediv(a, b b)</insert><dialog title="Insert truediv">truediv(%0, %1)</dialog><info title="Info window"></info></function>

3066

3067

3068

<description>__xor__{a, b}

3069

Return the bitwise exclusive or of a and b.</description>

3070

3071

3072

3073

3074

<description>__concat__{a, b}

3075

Return a + b for a and b sequences.</description>

3076

3077

<insert>concat(a, b b)</insert><dialog title="Insert concat">concat(%0, %1)</dialog><info title="Info window"></info></function>

3078

3079

3080

<description>__contains__{a, b}

3081

Return the outcome of the test b in a.

3082

Note the reversed operands. The name __contains__() was

3083

added in Python 2.0.</description>

3084

3085

<insert>contains(a, b b)</insert><dialog title="Insert contains">contains(%0, %1)</dialog><info title="Info window"></info></function>

3086

3087

3088

<description>Return the number of occurrences of b in a.</description>

3089

3090

<insert>countOf(a, b b)</insert><dialog title="Insert countOf">countOf(%0, %1)</dialog><info title="Info window"></info></function>

3091

3092

3093

<description>__delitem__{a, b}

3094

Remove the value of a at index b.</description>

3095

3096

<insert>delitem(a, b b)</insert><dialog title="Insert delitem">delitem(%0, %1)</dialog><info title="Info window"></info></function>

3097

3098

3099

<description>__delslice__{a, b, c}

3100

Delete the slice of a from index b to index c-1.</description>

3101

3102

<insert>delslice(a, b, c c)</insert><dialog title="Insert delslice">delslice(%0, %1, %2)</dialog><info title="Info window"></info></function>

3103

3104

3105

<description>__getitem__{a, b}

3106

Return the value of a at index b.</description>

3107

3108

<insert>getitem(a, b b)</insert><dialog title="Insert getitem">getitem(%0, %1)</dialog><info title="Info window"></info></function>

3109

3110

3111

<description>__getslice__{a, b, c}

3112

Return the slice of a from index b to index c-1.</description>

3113

3114

<insert>getslice(a, b, c c)</insert><dialog title="Insert getslice">getslice(%0, %1, %2)</dialog><info title="Info window"></info></function>

3115

3116

3117

<description>Return the index of the first of occurrence of b in a.</description>

3118

3119

<insert>indexOf(a, b b)</insert><dialog title="Insert indexOf">indexOf(%0, %1)</dialog><info title="Info window"></info></function>

3120

3121

3122

<description>__repeat__{a, b}

3123

Return a * b where a is a sequence and

3124

b is an integer.</description>

3125

3126

<insert>repeat(a, b b)</insert><dialog title="Insert repeat">repeat(%0, %1)</dialog><info title="Info window"></info></function>

3127

3128

3129

<description>2.0{Use contains() instead.}

3130

Alias for contains().</description>

3131

<param name="unspecifiedunspecified" optional="0">unspecifiedunspecified</param>

3132

<insert>sequenceIncludes(unspecifiedunspecified)</insert><dialog title="Insert sequenceIncludes">sequenceIncludes(%0)</dialog><info title="Info window"></info></function>

3133

3134

3135

<description>__setitem__{a, b, c}

3136

Set the value of a at index b to c.</description>

3137

3138

<insert>setitem(a, b, c c)</insert><dialog title="Insert setitem">setitem(%0, %1, %2)</dialog><info title="Info window"></info></function>

3139

3140

3141

<description>__setslice__{a, b, c, v}

3142

Set the slice of a from index b to index c-1 to the

3143

sequence v.</description>

3144

3145

<insert>setslice(a, b, c, v v)</insert><dialog title="Insert setslice">setslice(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

3146

3147

3148

<description>2.0{Use the callable() built-in function instead.}

3149

Returns true if the object o can be called like a function,

3150

otherwise it returns false. True is returned for functions, bound and

3151

unbound methods, class objects, and instance objects which support the

3152

__call__() method.</description>

3153

3154

<insert>isCallable(oo)</insert><dialog title="Insert isCallable">isCallable(%0)</dialog><info title="Info window"></info></function>

3155

3156

3157

<description>Returns true if the object o supports the mapping interface.

3158

This is true for dictionaries and all instance objects.

3159

There is no reliable way to test if an instance

3160

supports the complete mapping protocol since the interface itself is

3161

ill-defined. This makes this test less useful than it otherwise might

3162

be.</description>

3163

3164

<insert>isMappingType(oo)</insert><dialog title="Insert isMappingType">isMappingType(%0)</dialog><info title="Info window"></info></function>

3165

3166

3167

<description>Returns true if the object o represents a number. This is true

3168

for all numeric types implemented in C, and for all instance objects.

3169

There is no reliable way to test if an instance

3170

supports the complete numeric interface since the interface itself is

3171

ill-defined. This makes this test less useful than it otherwise might

3172

be.</description>

3173

3174

<insert>isNumberType(oo)</insert><dialog title="Insert isNumberType">isNumberType(%0)</dialog><info title="Info window"></info></function>

3175

3176

3177

<description>Returns true if the object o supports the sequence protocol.

3178

This returns true for all objects which define sequence methods in C,

3179

and for all instance objects. There is no reliable

3180

way to test if an instance supports the complete sequence interface

3181

since the interface itself is ill-defined. This makes this test less

3182

useful than it otherwise might be.</description>

3183

3184

<insert>isSequenceType(oo)</insert><dialog title="Insert isSequenceType">isSequenceType(%0)</dialog><info title="Info window"></info></function>

3185

3186

3187

<description>Return a callable object that fetches attr from its operand.

3188

After, f=attrgetter('name'), the call f(b) returns

3189

b.name.

3190

New in version 2.4</description>

3191

<param name="attrattr" optional="0">attrattr</param>

3192

<insert>attrgetter(attrattr)</insert><dialog title="Insert attrgetter">attrgetter(%0)</dialog><info title="Info window"></info></function>

3193

3194

3195

<description>Return a callable object that fetches item from its operand.

3196

After, f=itemgetter(2), the call f(b) returns

3197

b[2].

3198

New in version 2.4</description>

3199

<param name="itemitem" optional="0">itemitem</param>

3200

<insert>itemgetter(itemitem)</insert><dialog title="Insert itemgetter">itemgetter(%0)</dialog><info title="Info window"></info></function>

3201

3202

3203

</group>

3204

</group>

3205

3206

<description>Extract information and source code from live objects.

3207

New in version 2.1

3208

The inspect module provides several useful functions

3209

to help get information about live objects such as modules,

3210

classes, methods, functions, tracebacks, frame objects, and

3211

code objects. For example, it can help you examine the

3212

contents of a class, retrieve the source code of a method,

3213

extract and format the argument list for a function, or

3214

get all the information you need to display a detailed traceback.

3215

There are four main kinds of services provided by this module:

3216

type checking, getting source code, inspecting classes

3217

and functions, and examining the interpreter stack.

3218

</description>

3219

3220

<description>The getmembers() function retrieves the members

3221

of an object such as a class or module.

3222

The eleven functions whose names begin with ``is'' are mainly

3223

provided as convenient choices for the second argument to

3224

getmembers(). They also help you determine when

3225

you can expect to find the following special attributes:

3226

{c|l|l|c}{}{Type}{Attribute}{Description}{Notes}

3227

module{__doc__}{documentation string}{}

3228

{__file__}{filename (missing for built-in modules)}{}

3229

class{__doc__}{documentation string}{}

3230

{__module__}{name of module in which this class was defined}{}

3231

method{__doc__}{documentation string}{}

3232

{__name__}{name with which this method was defined}{}

3233

{im_class}{class object that asked for this method}{(1)}

3234

{im_func}{function object containing implementation of method}{}

3235

{im_self}{instance to which this method is bound, or None}{}

3236

function{__doc__}{documentation string}{}

3237

{__name__}{name with which this function was defined}{}

3238

{func_code}{code object containing compiled function bytecode}{}

3239

{func_defaults}{tuple of any default values for arguments}{}

3240

{func_doc}{(same as __doc__)}{}

3241

{func_globals}{global namespace in which this function was defined}{}

3242

{func_name}{(same as __name__)}{}

3243

traceback{tb_frame}{frame object at this level}{}

3244

{tb_lasti}{index of last attempted instruction in bytecode}{}

3245

{tb_lineno}{current line number in Python source code}{}

3246

{tb_next}{next inner traceback object (called by this level)}{}

3247

frame{f_back}{next outer frame object (this frame's caller)}{}

3248

{f_builtins}{built-in namespace seen by this frame}{}

3249

{f_code}{code object being executed in this frame}{}

3250

{f_exc_traceback}{traceback if raised in this frame, or None}{}

3251

{f_exc_type}{exception type if raised in this frame, or None}{}

3252

{f_exc_value}{exception value if raised in this frame, or None}{}

3253

{f_globals}{global namespace seen by this frame}{}

3254

{f_lasti}{index of last attempted instruction in bytecode}{}

3255

{f_lineno}{current line number in Python source code}{}

3256

{f_locals}{local namespace seen by this frame}{}

3257

{f_restricted}{0 or 1 if frame is in restricted execution mode}{}

3258

{f_trace}{tracing function for this frame, or None}{}

3259

code{co_argcount}{number of arguments (not including * or ** args)}{}

3260

{co_code}{string of raw compiled bytecode}{}

3261

{co_consts}{tuple of constants used in the bytecode}{}

3262

{co_filename}{name of file in which this code object was created}{}

3263

{co_firstlineno}{number of first line in Python source code}{}

3264

{co_flags}{bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg}{}

3265

{co_lnotab}{encoded mapping of line numbers to bytecode indices}{}

3266

{co_name}{name with which this code object was defined}{}

3267

{co_names}{tuple of names of local variables}{}

3268

{co_nlocals}{number of local variables}{}

3269

{co_stacksize}{virtual machine stack space required}{}

3270

{co_varnames}{tuple of names of arguments and local variables}{}

3271

builtin{__doc__}{documentation string}{}

3272

{__name__}{original name of this function or method}{}

3273

{__self__}{instance to which a method is bound, or None}{}

3274

Note:

3275

[(1)]

3276

Changed in version 2.2: im_class used to refer to the class that

3277

defined the method

3278

</description>

3279

3280

<description>Return all the members of an object in a list of (name, value) pairs

3281

sorted by name. If the optional predicate argument is supplied,

3282

only members for which the predicate returns a true value are included.</description>

3283

<param name="object" optional="0">object</param><param name="predicate" optional="1">predicate</param>

3284

<insert>getmembers(object, [predicate])</insert><dialog title="Insert getmembers">getmembers(%0, %1)</dialog><info title="Info window"></info></function>

3285

3286

3287

<description>Return a tuple of values that describe how Python will interpret the

3288

file identified by path if it is a module, or None if

3289

it would not be identified as a module. The return tuple is

3290

(name, suffix, mode, mtype), where

3291

name is the name of the module without the name of any

3292

enclosing package, suffix is the trailing part of the file

3293

name (which may not be a dot-delimited extension), mode is the

3294

open() mode that would be used ('r' or

3295

'rb'), and mtype is an integer giving the type of the

3296

module. mtype will have a value which can be compared to the

3297

constants defined in the imp module; see the

3298

documentation for that module for more information on module types.</description>

3299

<param name="pathpath" optional="0">pathpath</param>

3300

<insert>getmoduleinfo(pathpath)</insert><dialog title="Insert getmoduleinfo">getmoduleinfo(%0)</dialog><info title="Info window"></info></function>

3301

3302

3303

<description>Return the name of the module named by the file path, without

3304

including the names of enclosing packages. This uses the same

3305

algortihm as the interpreter uses when searching for modules. If

3306

the name cannot be matched according to the interpreter's rules,

3307

None is returned.</description>

3308

<param name="pathpath" optional="0">pathpath</param>

3309

<insert>getmodulename(pathpath)</insert><dialog title="Insert getmodulename">getmodulename(%0)</dialog><info title="Info window"></info></function>

3310

3311

3312

<description>Return true if the object is a module.</description>

3313

<param name="objectobject" optional="0">objectobject</param>

3314

<insert>ismodule(objectobject)</insert><dialog title="Insert ismodule">ismodule(%0)</dialog><info title="Info window"></info></function>

3315

3316

3317

<description>Return true if the object is a class.</description>

3318

<param name="objectobject" optional="0">objectobject</param>

3319

<insert>isclass(objectobject)</insert><dialog title="Insert isclass">isclass(%0)</dialog><info title="Info window"></info></function>

3320

3321

3322

<description>Return true if the object is a method.</description>

3323

<param name="objectobject" optional="0">objectobject</param>

3324

<insert>ismethod(objectobject)</insert><dialog title="Insert ismethod">ismethod(%0)</dialog><info title="Info window"></info></function>

3325

3326

3327

<description>Return true if the object is a Python function or unnamed (lambda) function.</description>

3328

<param name="objectobject" optional="0">objectobject</param>

3329

<insert>isfunction(objectobject)</insert><dialog title="Insert isfunction">isfunction(%0)</dialog><info title="Info window"></info></function>

3330

3331

3332

<description>Return true if the object is a traceback.</description>

3333

<param name="objectobject" optional="0">objectobject</param>

3334

<insert>istraceback(objectobject)</insert><dialog title="Insert istraceback">istraceback(%0)</dialog><info title="Info window"></info></function>

3335

3336

3337

<description>Return true if the object is a frame.</description>

3338

<param name="objectobject" optional="0">objectobject</param>

3339

<insert>isframe(objectobject)</insert><dialog title="Insert isframe">isframe(%0)</dialog><info title="Info window"></info></function>

3340

3341

3342

<description>Return true if the object is a code.</description>

3343

<param name="objectobject" optional="0">objectobject</param>

3344

<insert>iscode(objectobject)</insert><dialog title="Insert iscode">iscode(%0)</dialog><info title="Info window"></info></function>

3345

3346

3347

<description>Return true if the object is a built-in function.</description>

3348

<param name="objectobject" optional="0">objectobject</param>

3349

<insert>isbuiltin(objectobject)</insert><dialog title="Insert isbuiltin">isbuiltin(%0)</dialog><info title="Info window"></info></function>

3350

3351

3352

<description>Return true if the object is a user-defined or built-in function or method.</description>

3353

<param name="objectobject" optional="0">objectobject</param>

3354

<insert>isroutine(objectobject)</insert><dialog title="Insert isroutine">isroutine(%0)</dialog><info title="Info window"></info></function>

3355

3356

3357

<description>Return true if the object is a method descriptor, but not if ismethod() or isclass() or isfunction() are true.

3358

This is new as of Python 2.2, and, for example, is true of int.__add__.

3359

An object passing this test has a __get__ attribute but not a __set__

3360

attribute, but beyond that the set of attributes varies. __name__ is

3361

usually sensible, and __doc__ often is.

3362

Methods implemented via descriptors that also pass one of the other

3363

tests return false from the ismethoddescriptor() test, simply because

3364

the other tests promise more -- you can, e.g., count on having the

3365

im_func attribute (etc) when an object passes ismethod().</description>

3366

<param name="objectobject" optional="0">objectobject</param>

3367

<insert>ismethoddescriptor(objectobject)</insert><dialog title="Insert ismethoddescriptor">ismethoddescriptor(%0)</dialog><info title="Info window"></info></function>

3368

3369

3370

<description>Return true if the object is a data descriptor.

3371

Data descriptors have both a __get__ and a __set__ attribute. Examples are

3372

properties (defined in Python) and getsets and members (defined in C).

3373

Typically, data descriptors will also have __name__ and __doc__ attributes (properties, getsets, and members have both of these attributes), but this is not guaranteed.

3374

New in version 2.3</description>

3375

<param name="objectobject" optional="0">objectobject</param>

3376

<insert>isdatadescriptor(objectobject)</insert><dialog title="Insert isdatadescriptor">isdatadescriptor(%0)</dialog><info title="Info window"></info></function>

3377

3378

</group>

3379

3380

3381

<description>Get the documentation string for an object.

3382

All tabs are expanded to spaces. To clean up docstrings that are

3383

indented to line up with blocks of code, any whitespace than can be

3384

uniformly removed from the second line onwards is removed.</description>

3385

<param name="objectobject" optional="0">objectobject</param>

3386

<insert>getdoc(objectobject)</insert><dialog title="Insert getdoc">getdoc(%0)</dialog><info title="Info window"></info></function>

3387

3388

3389

<description>Return in a single string any lines of comments immediately preceding

3390

the object's source code (for a class, function, or method), or at the

3391

top of the Python source file (if the object is a module).</description>

3392

<param name="objectobject" optional="0">objectobject</param>

3393

<insert>getcomments(objectobject)</insert><dialog title="Insert getcomments">getcomments(%0)</dialog><info title="Info window"></info></function>

3394

3395

3396

<description>Return the name of the (text or binary) file in which an object was

3397

defined. This will fail with a TypeError if the object

3398

is a built-in module, class, or function.</description>

3399

<param name="objectobject" optional="0">objectobject</param>

3400

<insert>getfile(objectobject)</insert><dialog title="Insert getfile">getfile(%0)</dialog><info title="Info window"></info></function>

3401

3402

3403

<description>Try to guess which module an object was defined in.</description>

3404

<param name="objectobject" optional="0">objectobject</param>

3405

<insert>getmodule(objectobject)</insert><dialog title="Insert getmodule">getmodule(%0)</dialog><info title="Info window"></info></function>

3406

3407

3408

<description>Return the name of the Python source file in which an object was

3409

defined. This will fail with a TypeError if the object

3410

is a built-in module, class, or function.</description>

3411

<param name="objectobject" optional="0">objectobject</param>

3412

<insert>getsourcefile(objectobject)</insert><dialog title="Insert getsourcefile">getsourcefile(%0)</dialog><info title="Info window"></info></function>

3413

3414

3415

<description>Return a list of source lines and starting line number for an object.

3416

The argument may be a module, class, method, function, traceback, frame,

3417

or code object. The source code is returned as a list of the lines

3418

corresponding to the object and the line number indicates where in the

3419

original source file the first line of code was found. An

3420

IOError is raised if the source code cannot be retrieved.</description>

3421

<param name="objectobject" optional="0">objectobject</param>

3422

<insert>getsourcelines(objectobject)</insert><dialog title="Insert getsourcelines">getsourcelines(%0)</dialog><info title="Info window"></info></function>

3423

3424

3425

<description>Return the text of the source code for an object.

3426

The argument may be a module, class, method, function, traceback, frame,

3427

or code object. The source code is returned as a single string. An

3428

IOError is raised if the source code cannot be retrieved.</description>

3429

<param name="objectobject" optional="0">objectobject</param>

3430

<insert>getsource(objectobject)</insert><dialog title="Insert getsource">getsource(%0)</dialog><info title="Info window"></info></function>

3431

3432

</group>

3433

3434

3435

<description>Arrange the given list of classes into a hierarchy of nested lists.

3436

Where a nested list appears, it contains classes derived from the class

3437

whose entry immediately precedes the list. Each entry is a 2-tuple

3438

containing a class and a tuple of its base classes. If the unique

3439

argument is true, exactly one entry appears in the returned structure

3440

for each class in the given list. Otherwise, classes using multiple

3441

inheritance and their descendants will appear multiple times.</description>

3442

<param name="classes" optional="0">classes</param><param name="unique" optional="1">unique</param>

3443

<insert>getclasstree(classes, [unique])</insert><dialog title="Insert getclasstree">getclasstree(%0, %1)</dialog><info title="Info window"></info></function>

3444

3445

3446

<description>Get the names and default values of a function's arguments.

3447

A tuple of four things is returned: (args,

3448

varargs, varkw, defaults).

3449

args is a list of the argument names (it may contain nested lists).

3450

varargs and varkw are the names of the * and

3451

** arguments or None.

3452

defaults is a tuple of default argument values; if this tuple

3453

has n elements, they correspond to the last n elements

3454

listed in args.</description>

3455

<param name="funcfunc" optional="0">funcfunc</param>

3456

<insert>getargspec(funcfunc)</insert><dialog title="Insert getargspec">getargspec(%0)</dialog><info title="Info window"></info></function>

3457

3458

3459

<description>Get information about arguments passed into a particular frame.

3460

A tuple of four things is returned: (args,

3461

varargs, varkw, locals).

3462

args is a list of the argument names (it may contain nested

3463

lists).

3464

varargs and varkw are the names of the * and

3465

** arguments or None.

3466

locals is the locals dictionary of the given frame.</description>

3467

<param name="frameframe" optional="0">frameframe</param>

3468

<insert>getargvalues(frameframe)</insert><dialog title="Insert getargvalues">getargvalues(%0)</dialog><info title="Info window"></info></function>

3469

3470

3471

<description>Format a pretty argument spec from the four values returned by

3472

getargspec(). The other four arguments are the

3473

corresponding optional formatting functions that are called to turn

3474

names and values into strings.</description>

3475

<param name="args" optional="0">args</param><param name="varargs" optional="1">varargs</param><param name="varkw" optional="1">varkw</param><param name="defaults" optional="1">defaults</param><param name="argformat" optional="1">argformat</param><param name="varargsformat" optional="1">varargsformat</param><param name="varkwformat" optional="1">varkwformat</param><param name="defaultformat" optional="1">defaultformat</param>

3476

<insert>formatargspec(args, [varargs], [varkw], [defaults], [argformat], [varargsformat], [varkwformat], [defaultformat])</insert><dialog title="Insert formatargspec">formatargspec(%0, %1, %2, %3, %4, %5, %6, %7)</dialog><info title="Info window"></info></function>

3477

3478

3479

<description>Format a pretty argument spec from the four values returned by

3480

getargvalues(). The other four arguments are the

3481

corresponding optional formatting functions that are called to turn

3482

names and values into strings.</description>

3483

<param name="args" optional="0">args</param><param name="varargs" optional="1">varargs</param><param name="varkw" optional="1">varkw</param><param name="locals" optional="1">locals</param><param name="argformat" optional="1">argformat</param><param name="varargsformat" optional="1">varargsformat</param><param name="varkwformat" optional="1">varkwformat</param><param name="valueformat" optional="1">valueformat</param>

3484

<insert>formatargvalues(args, [varargs], [varkw], [locals], [argformat], [varargsformat], [varkwformat], [valueformat])</insert><dialog title="Insert formatargvalues">formatargvalues(%0, %1, %2, %3, %4, %5, %6, %7)</dialog><info title="Info window"></info></function>

3485

3486

3487

<description>Return a tuple of class cls's base classes, including cls, in

3488

method resolution order. No class appears more than once in this tuple.

3489

Note that the method resolution order depends on cls's type. Unless a

3490

very peculiar user-defined metatype is in use, cls will be the first

3491

element of the tuple.</description>

3492

<param name="clscls" optional="0">clscls</param>

3493

<insert>getmro(clscls)</insert><dialog title="Insert getmro">getmro(%0)</dialog><info title="Info window"></info></function>

3494

3495

</group>

3496

3497

<description>When the following functions return ``frame records,'' each record

3498

is a tuple of six items: the frame object, the filename,

3499

the line number of the current line, the function name, a list of

3500

lines of context from the source code, and the index of the current

3501

line within that list.

3502

The optional context argument specifies the number of lines of

3503

context to return, which are centered around the current line.

3504

Keeping references to frame objects, as found in

3505

the first element of the frame records these functions return, can

3506

cause your program to create reference cycles. Once a reference cycle

3507

has been created, the lifespan of all objects which can be accessed

3508

from the objects which form the cycle can become much longer even if

3509

Python's optional cycle detector is enabled. If such cycles must be

3510

created, it is important to ensure they are explicitly broken to avoid

3511

the delayed destruction of objects and increased memory consumption

3512

which occurs.

3513

</description>

3514

3515

<description>Get information about a frame or traceback object. A 5-tuple

3516

is returned, the last five elements of the frame's frame record.

3517

The optional second argument specifies the number of lines of context

3518

to return, which are centered around the current line.</description>

3519

<param name="frame" optional="0">frame</param><param name="context" optional="1">context</param>

3520

<insert>getframeinfo(frame, [context])</insert><dialog title="Insert getframeinfo">getframeinfo(%0, %1)</dialog><info title="Info window"></info></function>

3521

3522

3523

<description>Get a list of frame records for a frame and all higher (calling)

3524

frames.</description>

3525

<param name="frame" optional="0">frame</param><param name="context" optional="1">context</param>

3526

<insert>getouterframes(frame, [context])</insert><dialog title="Insert getouterframes">getouterframes(%0, %1)</dialog><info title="Info window"></info></function>

3527

3528

3529

<description>Get a list of frame records for a traceback's frame and all lower

3530

frames.</description>

3531

<param name="traceback" optional="0">traceback</param><param name="context" optional="1">context</param>

3532

<insert>getinnerframes(traceback, [context])</insert><dialog title="Insert getinnerframes">getinnerframes(%0, %1)</dialog><info title="Info window"></info></function>

3533

3534

3535

<description>Return the frame object for the caller's stack frame.</description>

3536

3537

<insert>currentframe()</insert><dialog title="Insert currentframe">currentframe()</dialog><info title="Info window"></info></function>

3538

3539

3540

<description>Return a list of frame records for the stack above the caller's

3541

frame.</description>

3542

<param name="context" optional="0">context</param>

3543

<insert>stack(context)</insert><dialog title="Insert stack">stack(%0)</dialog><info title="Info window"></info></function>

3544

3545

3546

<description>Return a list of frame records for the stack below the current

3547

exception.</description>

3548

<param name="context" optional="0">context</param>

3549

<insert>trace(context)</insert><dialog title="Insert trace">trace(%0)</dialog><info title="Info window"></info></function>

3550

3551

</group>

3552

</group>

3553

3554

<description>Print or retrieve a stack traceback.

3555

This module provides a standard interface to extract, format and print

3556

stack traces of Python programs. It exactly mimics the behavior of

3557

the Python interpreter when it prints a stack trace. This is useful

3558

when you want to print stack traces under program control, such as in a

3559

``wrapper'' around the interpreter.

3560

The module uses traceback objects --- this is the object type that is

3561

stored in the variables sys.exc_traceback (deprecated) and

3562

sys.last_traceback and returned as the third item from

3563

sys.exc_info().

3564

traceback

3565

The module defines the following functions:

3566

</description>

3567

3568

<description>Print up to limit stack trace entries from traceback. If

3569

limit is omitted or None, all entries are printed.

3570

If file is omitted or None, the output goes to

3571

sys.stderr; otherwise it should be an open file or file-like

3572

object to receive the output.</description>

3573

<param name="traceback" optional="0">traceback</param><param name="limit" optional="1">limit</param><param name="file" optional="1">file</param>

3574

<insert>print_tb(traceback, [limit], [file])</insert><dialog title="Insert print_tb">print_tb(%0, %1, %2)</dialog><info title="Info window"></info></function>

3575

3576

3577

<description>Print exception information and up to limit stack trace entries

3578

from traceback to file.

3579

This differs from print_tb() in the

3580

following ways: (1) if traceback is not None, it prints a

3581

header Traceback (most recent call last):; (2) it prints the

3582

exception type and value after the stack trace; (3) if

3583

type is SyntaxError and value has the

3584

appropriate format, it prints the line where the syntax error occurred

3585

with a caret indicating the approximate position of the error.</description>

3586

<param name="type" optional="0">type</param><param name="value" optional="0">value</param><param name="traceback" optional="0">traceback</param><param name="limit" optional="1">limit</param><param name="file" optional="1">file</param>

3587

<insert>print_exception(type, value, traceback, [limit], [file])</insert><dialog title="Insert print_exception">print_exception(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

3588

3589

3590

<description>This is a shorthand for print_exception(sys.exc_type,

3591

sys.exc_value, sys.exc_traceback, limit, file). (In

3592

fact, it uses sys.exc_info() to retrieve the same

3593

information in a thread-safe way instead of using the deprecated

3594

variables.)</description>

3595

<param name="limit" optional="0">limit</param><param name="file" optional="1">file</param>

3596

<insert>print_exc(limit, [file])</insert><dialog title="Insert print_exc">print_exc(%0, %1)</dialog><info title="Info window"></info></function>

3597

3598

3599

<description>This is like print_exc(limit) but returns a string

3600

instead of printing to a file.

3601

New in version 2.4</description>

3602

<param name="limit" optional="0">limit</param><param name="file" optional="1">file</param>

3603

<insert>format_exc(limit, [file])</insert><dialog title="Insert format_exc">format_exc(%0, %1)</dialog><info title="Info window"></info></function>

3604

3605

3606

<description>This is a shorthand for print_exception(sys.last_type,

3607

sys.last_value, sys.last_traceback, limit, file).</description>

3608

<param name="limit" optional="0">limit</param><param name="file" optional="1">file</param>

3609

<insert>print_last(limit, [file])</insert><dialog title="Insert print_last">print_last(%0, %1)</dialog><info title="Info window"></info></function>

3610

3611

3612

<description>This function prints a stack trace from its invocation point. The

3613

optional f argument can be used to specify an alternate stack

3614

frame to start. The optional limit and file arguments have the

3615

same meaning as for print_exception().</description>

3616

<param name="f" optional="0">f</param><param name="limit" optional="1">limit</param><param name="file" optional="1">file</param>

3617

<insert>print_stack(f, [limit], [file])</insert><dialog title="Insert print_stack">print_stack(%0, %1, %2)</dialog><info title="Info window"></info></function>

3618

3619

3620

<description>Return a list of up to limit ``pre-processed'' stack trace

3621

entries extracted from the traceback object traceback. It is

3622

useful for alternate formatting of stack traces. If limit is

3623

omitted or None, all entries are extracted. A

3624

``pre-processed'' stack trace entry is a quadruple (filename,

3625

line number, function name, text) representing

3626

the information that is usually printed for a stack trace. The

3627

text is a string with leading and trailing whitespace

3628

stripped; if the source is not available it is None.</description>

3629

<param name="traceback" optional="0">traceback</param><param name="limit" optional="1">limit</param>

3630

<insert>extract_tb(traceback, [limit])</insert><dialog title="Insert extract_tb">extract_tb(%0, %1)</dialog><info title="Info window"></info></function>

3631

3632

3633

<description>Extract the raw traceback from the current stack frame. The return

3634

value has the same format as for extract_tb(). The

3635

optional f and limit arguments have the same meaning as

3636

for print_stack().</description>

3637

<param name="f" optional="0">f</param><param name="limit" optional="1">limit</param>

3638

<insert>extract_stack(f, [limit])</insert><dialog title="Insert extract_stack">extract_stack(%0, %1)</dialog><info title="Info window"></info></function>

3639

3640

3641

<description>Given a list of tuples as returned by extract_tb() or

3642

extract_stack(), return a list of strings ready for

3643

printing. Each string in the resulting list corresponds to the item

3644

with the same index in the argument list. Each string ends in a

3645

newline; the strings may contain internal newlines as well, for those

3646

items whose source text line is not None.</description>

3647

<param name="listlist" optional="0">listlist</param>

3648

<insert>format_list(listlist)</insert><dialog title="Insert format_list">format_list(%0)</dialog><info title="Info window"></info></function>

3649

3650

3651

<description>Format the exception part of a traceback. The arguments are the

3652

exception type and value such as given by sys.last_type and

3653

sys.last_value. The return value is a list of strings, each

3654

ending in a newline. Normally, the list contains a single string;

3655

however, for SyntaxError exceptions, it contains several

3656

lines that (when printed) display detailed information about where the

3657

syntax error occurred. The message indicating which exception

3658

occurred is the always last string in the list.</description>

3659

<param name="type" optional="0">type</param><param name="value value" optional="0">value value</param>

3660

<insert>format_exception_only(type, value value)</insert><dialog title="Insert format_exception_only">format_exception_only(%0, %1)</dialog><info title="Info window"></info></function>

3661

3662

3663

<description>Format a stack trace and the exception information. The arguments have the same meaning as the corresponding arguments to

3664

print_exception(). The return value is a list of strings,

3665

each ending in a newline and some containing internal newlines. When

3666

these lines are concatenated and printed, exactly the same text is

3667

printed as does print_exception().</description>

3668

<param name="type" optional="0">type</param><param name="value" optional="0">value</param><param name="tb" optional="0">tb</param><param name="limit" optional="1">limit</param>

3669

<insert>format_exception(type, value, tb, [limit])</insert><dialog title="Insert format_exception">format_exception(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

3670

3671

3672

<description>A shorthand for format_list(extract_tb(tb, limit)).</description>

3673

<param name="tb" optional="0">tb</param><param name="limit" optional="1">limit</param>

3674

<insert>format_tb(tb, [limit])</insert><dialog title="Insert format_tb">format_tb(%0, %1)</dialog><info title="Info window"></info></function>

3675

3676

3677

<description>A shorthand for format_list(extract_stack(f, limit)).</description>

3678

<param name="f" optional="0">f</param><param name="limit" optional="1">limit</param>

3679

<insert>format_stack(f, [limit])</insert><dialog title="Insert format_stack">format_stack(%0, %1)</dialog><info title="Info window"></info></function>

3680

3681

3682

<description>This function returns the current line number set in the traceback

3683

object. This function was necessary because in versions of Python

3684

prior to 2.3 when the -O flag was passed to Python the

3685

tb.tb_lineno was not updated correctly. This function

3686

has no use in versions past 2.3.</description>

3687

3688

<insert>tb_lineno(tbtb)</insert><dialog title="Insert tb_lineno">tb_lineno(%0)</dialog><info title="Info window"></info></function>

3689

3690

3691

</group>

3692

</group>

3693

3694

<description>This module provides random access to individual lines

3695

from text files.

3696

The linecache module allows one to get any line from any file,

3697

while attempting to optimize internally, using a cache, the common case

3698

where many lines are read from a single file. This is used by the

3699

traceback module to retrieve source lines for inclusion in the formatted traceback.

3700

The linecache module defines the following functions:

3701

</description>

3702

3703

<description>Get line lineno from file named filename. This function

3704

will never throw an exception --- it will return '' on errors

3705

(the terminating newline character will be included for lines that are

3706

found).

3707

If a file named filename is not found, the function will look

3708

for it in the modulemodule{search}{path} search path,

3709

sys.path.</description>

3710

<param name="filename" optional="0">filename</param><param name="lineno lineno" optional="0">lineno lineno</param>

3711

<insert>getline(filename, lineno lineno)</insert><dialog title="Insert getline">getline(%0, %1)</dialog><info title="Info window"></info></function>

3712

3713

3714

<description>Clear the cache. Use this function if you no longer need lines from

3715

files previously read using getline().</description>

3716

3717

<insert>clearcache()</insert><dialog title="Insert clearcache">clearcache()</dialog><info title="Info window"></info></function>

3718

3719

3720

<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>

3721

3722

<insert>checkcache()</insert><dialog title="Insert checkcache">checkcache()</dialog><info title="Info window"></info></function>

3723

3724

</group>

3725

3726

<description>Convert Python objects to streams of bytes and back.

3727

% Substantial improvements by Jim Kerr <jbkerr@sr.hp.com>.

3728

% Rewritten by Barry Warsaw <barry@zope.com>

3729

</description>

3730

3731

<description>The pickle module has an optimized cousin called the

3732

cPickle module. As its name implies, cPickle is

3733

written in C, so it can be up to 1000 times faster than

3734

pickle. However it does not support subclassing of the

3735

Pickler() and Unpickler() classes, because in

3736

cPickle these are functions, not classes. Most applications

3737

have no need for this functionality, and can benefit from the improved

3738

performance of cPickle. Other than that, the interfaces of

3739

the two modules are nearly identical; the common interface is

3740

described in this manual and differences are pointed out where

3741

necessary. In the following discussions, we use the term ``pickle''

3742

to collectively describe the pickle and

3743

cPickle modules.

3744

The data streams the two modules produce are guaranteed to be

3745

interchangeable.

3746

Python has a more primitive serialization module called

3747

marshal, but in general

3748

pickle should always be the preferred way to serialize Python

3749

objects. marshal exists primarily to support Python's

3750

.pyc files.

3751

The pickle module differs from marshal several

3752

significant ways:

3753

The pickle module keeps track of the objects it has

3754

already serialized, so that later references to the same object

3755

won't be serialized again. marshal doesn't do this.

3756

This has implications both for recursive objects and object

3757

sharing. Recursive objects are objects that contain references

3758

to themselves. These are not handled by marshal, and in fact,

3759

attempting to marshal recursive objects will crash your Python

3760

interpreter. Object sharing happens when there are multiple

3761

references to the same object in different places in the object

3762

hierarchy being serialized. pickle stores such objects

3763

only once, and ensures that all other references point to the

3764

master copy. Shared objects remain shared, which can be very

3765

important for mutable objects.

3766

marshal cannot be used to serialize user-defined

3767

classes and their instances. pickle can save and

3768

restore class instances transparently, however the class

3769

definition must be importable and live in the same module as

3770

when the object was stored.

3771

The marshal serialization format is not guaranteed to

3772

be portable across Python versions. Because its primary job in

3773

life is to support .pyc files, the Python implementers

3774

reserve the right to change the serialization format in

3775

non-backwards compatible ways should the need arise. The

3776

pickle serialization format is guaranteed to be

3777

backwards compatible across Python releases.

3778

[warning]

3779

The pickle module is not intended to be secure against

3780

erroneous or maliciously constructed data. Never unpickle data

3781

received from an untrusted or unauthenticated source.

3782

Note that serialization is a more primitive notion than persistence;

3783

although

3784

pickle reads and writes file objects, it does not handle the

3785

issue of naming persistent objects, nor the (even more complicated)

3786

issue of concurrent access to persistent objects. The pickle

3787

module can transform a complex object into a byte stream and it can

3788

transform the byte stream into an object with the same internal

3789

structure. Perhaps the most obvious thing to do with these byte

3790

streams is to write them onto a file, but it is also conceivable to

3791

send them across a network or store them in a database. The module

3792

shelve provides a simple interface

3793

to pickle and unpickle objects on DBM-style database files.

3794

</description>

3795

</group>

3796

3797

<description>The data format used by pickle is Python-specific. This has

3798

the advantage that there are no restrictions imposed by external

3799

standards such as XDR</description>

3800

</group>

3801

3802

<description>To serialize an object hierarchy, you first create a pickler, then you

3803

call the pickler's dump() method. To de-serialize a data

3804

stream, you first create an unpickler, then you call the unpickler's

3805

load() method. The pickle module provides the

3806

following constant:

3807

{HIGHEST_PROTOCOL}

3808

The highest protocol version available. This value can be passed

3809

as a protocol value.

3810

New in version 2.3

3811

The pickle module provides the

3812

following functions to make this process more convenient:

3813

</description>

3814

3815

<description>Write a pickled representation of object to the open file object

3816

file. This is equivalent to

3817

Pickler(file, protocol, bin).dump(object).

3818

If the protocol parameter is ommitted, protocol 0 is used.

3819

If protocol is specified as a negative value

3820

or HIGHEST_PROTOCOL,

3821

the highest protocol version will be used.

3822

Changed in version 2.3: The protocol parameter was added.

3823

The bin parameter is deprecated and only provided

3824

for backwards compatibility. You should use the protocol

3825

parameter instead

3826

If the optional bin argument is true, the binary pickle format

3827

is used; otherwise the (less efficient) text pickle format is used

3828

(for backwards compatibility, this is the default).

3829

file must have a write() method that accepts a single

3830

string argument. It can thus be a file object opened for writing, a

3831

StringIO object, or any other custom

3832

object that meets this interface.</description>

3833

<param name="object" optional="0">object</param><param name="file" optional="0">file</param><param name="protocol" optional="1">protocol</param><param name="bin" optional="1">bin</param>

3834

<insert>dump(object, file, [protocol], [bin])</insert><dialog title="Insert dump">dump(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

3835

3836

3837

<description>Read a string from the open file object file and interpret it as

3838

a pickle data stream, reconstructing and returning the original object

3839

hierarchy. This is equivalent to Unpickler(file).load().

3840

file must have two methods, a read() method that takes

3841

an integer argument, and a readline() method that requires no

3842

arguments. Both methods should return a string. Thus file can

3843

be a file object opened for reading, a

3844

StringIO object, or any other custom

3845

object that meets this interface.

3846

This function automatically determines whether the data stream was

3847

written in binary mode or not.</description>

3848

<param name="filefile" optional="0">filefile</param>

3849

<insert>load(filefile)</insert><dialog title="Insert load">load(%0)</dialog><info title="Info window"></info></function>

3850

3851

3852

<description>Return the pickled representation of the object as a string, instead

3853

of writing it to a file.

3854

If the protocol parameter is ommitted, protocol 0 is used.

3855

If protocol is specified as a negative value

3856

or HIGHEST_PROTOCOL,

3857

the highest protocol version will be used.

3858

Changed in version 2.3: The protocol parameter was added.

3859

The bin parameter is deprecated and only provided

3860

for backwards compatibility. You should use the protocol

3861

parameter instead

3862

If the optional bin argument is

3863

true, the binary pickle format is used; otherwise the (less efficient)

3864

text pickle format is used (this is the default).</description>

3865

<param name="object" optional="0">object</param><param name="protocol" optional="1">protocol</param><param name="bin" optional="1">bin</param>

3866

<insert>dumps(object, [protocol], [bin])</insert><dialog title="Insert dumps">dumps(%0, %1, %2)</dialog><info title="Info window"></info></function>

3867

3868

3869

<description>Read a pickled object hierarchy from a string. Characters in the

3870

string past the pickled object's representation are ignored.</description>

3871

<param name="stringstring" optional="0">stringstring</param>

3872

<insert>loads(stringstring)</insert><dialog title="Insert loads">loads(%0)</dialog><info title="Info window"></info></function>

3873

3874

3875

<description>This takes a file-like object to which it will write a pickle data

3876

stream. If the protocol parameter is ommitted, protocol 0 is used.

3877

If protocol is specified as a negative value,

3878

the highest protocol version will be used.

3879

Changed in version 2.3: The bin parameter is deprecated and only provided

3880

for backwards compatibility. You should use the protocol

3881

parameter instead

3882

Optional bin if true, tells the pickler to use the more

3883

efficient binary pickle format, otherwise the ASCII format is used

3884

(this is the default).

3885

file must have a write() method that accepts a single

3886

string argument. It can thus be an open file object, a

3887

StringIO object, or any other custom

3888

object that meets this interface.</description>

3889

<param name="file" optional="0">file</param><param name="protocol" optional="1">protocol</param><param name="bin" optional="1">bin</param>

3890

<insert>Pickler(file, [protocol], [bin])</insert><dialog title="Insert Pickler">Pickler(%0, %1, %2)</dialog><info title="Info window"></info></function>

3891

3892

3893

<description>Write a pickled representation of object to the open file object

3894

given in the constructor. Either the binary or ASCII format will

3895

be used, depending on the value of the bin flag passed to the

3896

constructor.</description>

3897

<param name="objectobject" optional="0">objectobject</param>

3898

<insert>dump(objectobject)</insert><dialog title="Insert dump">dump(%0)</dialog><info title="Info window"></info></function>

3899

3900

3901

<description>Clears the pickler's ``memo''. The memo is the data structure that

3902

remembers which objects the pickler has already seen, so that shared

3903

or recursive objects pickled by reference and not by value. This

3904

method is useful when re-using picklers.

3905

Prior to Python 2.3, clear_memo() was only available on the

3906

picklers created by cPickle. In the pickle module,

3907

picklers have an instance variable called memo which is a

3908

Python dictionary. So to clear the memo for a pickle module

3909

pickler, you could do the following:

3910

mypickler.memo.clear()

3911

Code that does not need to support older versions of Python should

3912

simply use clear_memo().

3913

</description>

3914

3915

<insert>clear_memo()</insert><dialog title="Insert clear_memo">clear_memo()</dialog><info title="Info window"></info></function>

3916

3917

3918

<description>This takes a file-like object from which it will read a pickle data

3919

stream. This class automatically determines whether the data stream

3920

was written in binary mode or not, so it does not need a flag as in

3921

the Pickler factory.

3922

file must have two methods, a read() method that takes

3923

an integer argument, and a readline() method that requires no

3924

arguments. Both methods should return a string. Thus file can

3925

be a file object opened for reading, a

3926

StringIO object, or any other custom

3927

object that meets this interface.</description>

3928

<param name="filefile" optional="0">filefile</param>

3929

<insert>Unpickler(filefile)</insert><dialog title="Insert Unpickler">Unpickler(%0)</dialog><info title="Info window"></info></function>

3930

3931

3932

<description>Read a pickled object representation from the open file object given

3933

in the constructor, and return the reconstituted object hierarchy

3934

specified therein.</description>

3935

3936

3937

3938

3939

<description>This is just like load() except that it doesn't actually

3940

create any objects. This is useful primarily for finding what's

3941

called ``persistent ids'' that may be referenced in a pickle data

3942

stream. See section~pickle-protocol below for more details.

3943

Note: the noload() method is currently only

3944

available on Unpickler objects created with the

3945

cPickle module. pickle module Unpicklers do

3946

not have the noload() method.</description>

3947

3948

<insert>noload()</insert><dialog title="Insert noload">noload()</dialog><info title="Info window"></info></function>

3949

3950

</group>

3951

3952

<description>The following types can be pickled:

3953

None, True, and False

3954

integers, long integers, floating point numbers, complex numbers

3955

normal and Unicode strings

3956

tuples, lists, and dictionaries containing only picklable objects

3957

functions defined at the top level of a module

3958

built-in functions defined at the top level of a module

3959

classes that are defined at the top level of a module

3960

instances of such classes whose __dict__ or

3961

__setstate__() is picklable (see

3962

section~pickle-protocol for details)

3963

Attempts to pickle unpicklable objects will raise the

3964

PicklingError exception; when this happens, an unspecified

3965

number of bytes may have already been written to the underlying file.

3966

Note that functions (built-in and user-defined) are pickled by ``fully

3967

qualified'' name reference, not by value. This means that only the

3968

function name is pickled, along with the name of module the function

3969

is defined in. Neither the function's code, nor any of its function

3970

attributes are pickled. Thus the defining module must be importable

3971

in the unpickling environment, and the module must contain the named

3972

object, otherwise an exception will be raised.The exception

3973

raised will likely be an ImportError or an

3974

AttributeError but it could be something else.

3975

Similarly, classes are pickled by named reference, so the same

3976

restrictions in the unpickling environment apply. Note that none of

3977

the class's code or data is pickled, so in the following example the

3978

class attribute attr is not restored in the unpickling

3979

environment:

3980

class Foo:

3981

attr = 'a class attr'

3982

picklestring = pickle.dumps(Foo)

3983

These restrictions are why picklable functions and classes must be

3984

defined in the top level of a module.

3985

Similarly, when class instances are pickled, their class's code and

3986

data are not pickled along with them. Only the instance data are

3987

pickled. This is done on purpose, so you can fix bugs in a class or

3988

add methods to the class and still load objects that were created with

3989

an earlier version of the class. If you plan to have long-lived

3990

objects that will see many versions of a class, it may be worthwhile

3991

to put a version number in the objects so that suitable conversions

3992

can be made by the class's __setstate__() method.

3993

</description>

3994

</group>

3995

3996

</group>

3997

3998

<description>By default, unpickling will import any class that it finds in the

3999

pickle data. You can control exactly what gets unpickled and what

4000

gets called by customizing your unpickler. Unfortunately, exactly how

4001

you do this is different depending on whether you're using

4002

pickle or cPickle.A word of caution: the

4003

mechanisms described here use internal attributes and methods, which

4004

are subject to change in future versions of Python. We intend to

4005

someday provide a common interface for controlling this behavior,

4006

which will work in either pickle or cPickle.

4007

In the pickle module, you need to derive a subclass from

4008

Unpickler, overriding the load_global()

4009

method. load_global() should read two lines from the pickle

4010

data stream where the first line will the name of the module

4011

containing the class and the second line will be the name of the

4012

instance's class. It then looks up the class, possibly importing the

4013

module and digging out the attribute, then it appends what it finds to

4014

the unpickler's stack. Later on, this class will be assigned to the

4015

__class__ attribute of an empty class, as a way of magically

4016

creating an instance without calling its class's __init__().

4017

Your job (should you choose to accept it), would be to have

4018

load_global() push onto the unpickler's stack, a known safe

4019

version of any class you deem safe to unpickle. It is up to you to

4020

produce such a class. Or you could raise an error if you want to

4021

disallow all unpickling of instances. If this sounds like a hack,

4022

you're right. Refer to the source code to make this work.

4023

Things are a little cleaner with cPickle, but not by much.

4024

To control what gets unpickled, you can set the unpickler's

4025

find_global attribute to a function or None. If it is

4026

None then any attempts to unpickle instances will raise an

4027

UnpicklingError. If it is a function,

4028

then it should accept a module name and a class name, and return the

4029

corresponding class object. It is responsible for looking up the

4030

class and performing any necessary imports, and it may raise an

4031

error to prevent instances of the class from being unpickled.

4032

The moral of the story is that you should be really careful about the

4033

source of the strings your application unpickles.

4034

</description>

4035

</group>

4036

4037

</group>

4038

</group>

4039

4040

<description>Python object persistence.

4041

A ``shelf'' is a persistent, dictionary-like object. The difference

4042

with ``dbm'' databases is that the values (not the keys!) in a shelf

4043

can be essentially arbitrary Python objects --- anything that the

4044

pickle module can handle. This includes most class

4045

instances, recursive data types, and objects containing lots of shared sub-objects. The keys are ordinary strings.

4046

pickle

4047

</description>

4048

4049

<description>Open a persistent dictionary. The filename specified is the base filename

4050

for the underlying database. As a side-effect, an extension may be added to

4051

the filename and more than one file may be created. By default, the

4052

underlying database file is opened for reading and writing. The optional

4053

{}flag pararameter has the same interpretation as the flag

4054

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

4055

protocol parameter. Changed in version 2.3: The protocol

4056

parameter was added. The binary parameter is deprecated

4057

and provided for backwards compatibility only

4058

By default, mutations to persistent-dictionary mutable entries are not

4059

automatically written back. If the optional writeback parameter

4060

is set to {}True, all entries accessed are cached in memory, and

4061

written back at close time; this can make it handier to mutate mutable

4062

entries in the persistent dictionary, but, if many entries are

4063

accessed, it can consume vast amounts of memory for the cache, and it

4064

can make the close operation very slow since all accessed entries are

4065

written back (there is no way to determine which accessed entries are

4066

mutable, nor which ones were actually mutated).</description>

4067

<param name="filename" optional="0">filename</param><param name="flag" optional="1" default="'c'">flag</param><param name="protocol" optional="1" default="None">protocol</param><param name="writeback" optional="1" default="False">writeback</param><param name="binary" optional="1" default="None">binary</param>

4068

<insert>open(filename, [flag='c'], [protocol=None], [writeback=False], [binary=None])</insert><dialog title="Insert open">open(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

4069

4070

4071

<description>The choice of which database package will be used

4072

(such as dbm, gdbm or bsddb) depends on

4073

which interface is available. Therefore it is not safe to open the database

4074

directly using dbm. The database is also (unfortunately) subject

4075

to the limitations of dbm, if it is used --- this means

4076

that (the pickled representation of) the objects stored in the

4077

database should be fairly small, and in rare cases key collisions may

4078

cause the database to refuse updates.

4079

dbm

4080

gdbm

4081

bsddb

4082

Depending on the implementation, closing a persistent dictionary may

4083

or may not be necessary to flush changes to disk. The __del__

4084

method of the Shelf class calls the close method, so the

4085

programmer generally need not do this explicitly.

4086

The shelve module does not support concurrent read/write

4087

access to shelved objects. (Multiple simultaneous read accesses are

4088

safe.) When a program has a shelf open for writing, no other program

4089

should have it open for reading or writing. file locking can

4090

be used to solve this, but this differs across versions and

4091

requires knowledge about the database implementation used.

4092

</description>

4093

4094

<description>A subclass of UserDict.DictMixin which stores pickled values in the

4095

dict object. By default, version 0 pickles are used to serialize values. The

4096

version of the pickle protocol can be specified with the

4097

protocol parameter. See the pickle documentation for a

4098

discussion of the pickle protocols. Changed in version 2.3: The protocol

4099

parameter was added. The binary parameter is deprecated and

4100

provided for backwards compatibility only

4101

If the writeback parameter is True, the object will hold a

4102

cache of all entries accessed and write them back to the dict at

4103

sync and close times. This allows natural operations on mutable entries,

4104

but can consume much more memory and make sync and close take a long time.</description>

4105

<param name="dict" optional="0">dict</param><param name="protocol" optional="1" default="None">protocol</param><param name="writeback" optional="1" default="False">writeback</param><param name="binary" optional="1" default="None">binary</param>

4106

<insert>Shelf(dict, [protocol=None], [writeback=False], [binary=None])</insert><dialog title="Insert Shelf">Shelf(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

4107

4108

4109

<description>A subclass of Shelf which exposes first,

4110

next, previous, last and

4111

set_location which are available in the bsddb module

4112

but not in other database modules. The dict object passed to

4113

the constructor must support those methods. This is generally

4114

accomplished by calling one of bsddb.hashopen,

4115

bsddb.btopen or bsddb.rnopen. The optional

4116

protocol, writeback, and binary parameters have the

4117

same interpretation as for the Shelf class.</description>

4118

<param name="dict" optional="0">dict</param><param name="protocol" optional="1" default="None">protocol</param><param name="writeback" optional="1" default="False">writeback</param><param name="binary" optional="1" default="None">binary</param>

4119

<insert>BsdDbShelf(dict, [protocol=None], [writeback=False], [binary=None])</insert><dialog title="Insert BsdDbShelf">BsdDbShelf(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

4120

4121

4122

<description>A subclass of Shelf which accepts a filename instead of

4123

a dict-like object. The underlying file will be opened using

4124

{}anydbm.open. By default, the file will be created and

4125

opened for both read and write. The optional flag parameter has

4126

the same interpretation as for the open function. The

4127

optional protocol, writeback, and binary parameters

4128

have the same interpretation as for the Shelf class.</description>

4129

<param name="filename" optional="0">filename</param><param name="flag" optional="1" default="'c'">flag</param><param name="protocol" optional="1" default="None">protocol</param><param name="writeback" optional="1" default="False">writeback</param><param name="binary" optional="1" default="None">binary</param>

4130

<insert>DbfilenameShelf(filename, [flag='c'], [protocol=None], [writeback=False], [binary=None])</insert><dialog title="Insert DbfilenameShelf">DbfilenameShelf(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

4131

4132

</group>

4133

4134

</group>

4135

</group>

4136

4137

</group>

4138

4139

<description>Convert Python objects to streams of bytes and back

4140

(with different constraints).

4141

This module contains functions that can read and write Python

4142

values in a binary format. The format is specific to Python, but

4143

independent of machine architecture issues (e.g., you can write a

4144

Python value to a file on a PC, transport the file to a Sun, and read

4145

it back there). Details of the format are undocumented on purpose;

4146

it may change between Python versions (although it rarely

4147

does).The name of this module stems from a bit of

4148

terminology used by the designers of Modula-3 (amongst others), who

4149

use the term ``marshalling'' for shipping of data around in a

4150

self-contained form. Strictly speaking, ``to marshal'' means to

4151

convert some data from internal to external form (in an RPC buffer for

4152

instance) and ``unmarshalling'' for the reverse process.

4153

This is not a general ``persistence'' module. For general persistence

4154

and transfer of Python objects through RPC calls, see the modules

4155

pickle and shelve. The marshal module exists

4156

mainly to support reading and writing the ``pseudo-compiled'' code for

4157

Python modules of .pyc files. Therefore, the Python

4158

maintainers reserve the right to modify the marshal format in backward

4159

incompatible ways should the need arise. If you're serializing and

4160

de-serializing Python objects, use the pickle module instead. pickle

4161

shelve

4162

code

4163

[warning]

4164

The marshal module is not intended to be secure against

4165

erroneous or maliciously constructed data. Never unmarshal data

4166

received from an untrusted or unauthenticated source.

4167

Not all Python object types are supported; in general, only objects

4168

whose value is independent from a particular invocation of Python can

4169

be written and read by this module. The following types are supported:

4170

None, integers, long integers, floating point numbers,

4171

strings, Unicode objects, tuples, lists, dictionaries, and code

4172

objects, where it should be understood that tuples, lists and

4173

dictionaries are only supported as long as the values contained

4174

therein are themselves supported; and recursive lists and dictionaries

4175

should not be written (they will cause infinite loops).

4176

Caveat: On machines where C's long int type has more than

4177

32 bits (such as the DEC Alpha), it is possible to create plain Python

4178

integers that are longer than 32 bits.

4179

If such an integer is marshaled and read back in on a machine where

4180

C's long int type has only 32 bits, a Python long integer object

4181

is returned instead. While of a different type, the numeric value is

4182

the same. (This behavior is new in Python 2.2. In earlier versions,

4183

all but the least-significant 32 bits of the value were lost, and a

4184

warning message was printed.)

4185

There are functions that read/write files as well as functions

4186

operating on strings.

4187

The module defines these functions:

4188

</description>

4189

4190

<description>Write the value on the open file. The value must be a supported

4191

type. The file must be an open file object such as

4192

sys.stdout or returned by open() or

4193

posix.popen(). It must be opened in binary mode

4194

('wb' or 'w+b').

4195

If the value has (or contains an object that has) an unsupported type,

4196

a ValueError exception is raised --- but garbage data

4197

will also be written to the file. The object will not be properly

4198

read back by load().</description>

4199

<param name="value" optional="0">value</param><param name="file file" optional="0">file file</param>

4200

<insert>dump(value, file file)</insert><dialog title="Insert dump">dump(%0, %1)</dialog><info title="Info window"></info></function>

4201

4202

4203

<description>Read one value from the open file and return it. If no valid value

4204

is read, raise EOFError, ValueError or

4205

TypeError. The file must be an open file object opened

4206

in binary mode ('rb' or 'r+b').

4207

If an object containing an unsupported type was

4208

marshalled with dump(), load() will substitute

4209

None for the unmarshallable type.</description>

4210

<param name="filefile" optional="0">filefile</param>

4211

<insert>load(filefile)</insert><dialog title="Insert load">load(%0)</dialog><info title="Info window"></info></function>

4212

4213

4214

<description>Return the string that would be written to a file by

4215

dump(value, file). The value must be a supported

4216

type. Raise a ValueError exception if value has (or

4217

contains an object that has) an unsupported type.</description>

4218

<param name="valuevalue" optional="0">valuevalue</param>

4219

<insert>dumps(valuevalue)</insert><dialog title="Insert dumps">dumps(%0)</dialog><info title="Info window"></info></function>

4220

4221

4222

<description>Convert the string to a value. If no valid value is found, raise

4223

EOFError, ValueError or

4224

TypeError. Extra characters in the string are ignored.</description>

4225

<param name="stringstring" optional="0">stringstring</param>

4226

<insert>loads(stringstring)</insert><dialog title="Insert loads">loads(%0)</dialog><info title="Info window"></info></function>

4227

4228

</group>

4229

4230

<description>Issue warning messages and control their disposition.

4231

</description>

4232

4233

<description>There are a number of built-in exceptions that represent warning

4234

categories. This categorization is useful to be able to filter out

4235

groups of warnings. The following warnings category classes are

4236

currently defined:

4237

{l|l}{exception}{Class}{Description}

4238

Warning{This is the base class of all warning category

4239

classes. It is a subclass of Exception.}

4240

UserWarning{The default category for warn().}

4241

DeprecationWarning{Base category for warnings about

4242

deprecated features.}

4243

SyntaxWarning{Base category for warnings about dubious

4244

syntactic features.}

4245

RuntimeWarning{Base category for warnings about dubious

4246

runtime features.}

4247

FutureWarning{Base category for warnings about constructs

4248

that will change semantically in the future.}

4249

While these are technically built-in exceptions, they are documented

4250

here, because conceptually they belong to the warnings mechanism.

4251

User code can define additional warning categories by subclassing one

4252

of the standard warning categories. A warning category must always be

4253

a subclass of the Warning class.

4254

</description>

4255

</group>

4256

4257

<description>The warnings filter controls whether warnings are ignored, displayed,

4258

or turned into errors (raising an exception).

4259

Conceptually, the warnings filter maintains an ordered list of filter

4260

specifications; any specific warning is matched against each filter

4261

specification in the list in turn until a match is found; the match

4262

determines the disposition of the match. Each entry is a tuple of the

4263

form (action, message, category, module,

4264

lineno), where:

4265

action is one of the following strings:

4266

{l|l}{code}{Value}{Disposition}

4267

"error"{turn matching warnings into exceptions}

4268

"ignore"{never print matching warnings}

4269

"always"{always print matching warnings}

4270

"default"{print the first occurrence of matching

4271

warnings for each location where the warning is issued}

4272

"module"{print the first occurrence of matching

4273

warnings for each module where the warning is issued}

4274

"once"{print only the first occurrence of matching

4275

warnings, regardless of location}

4276

message is a string containing a regular expression that

4277

the warning message must match (the match is compiled to always be case-insensitive) category is a class (a subclass of Warning) of

4278

which the warning category must be a subclass in order to match

4279

module is a string containing a regular expression that the module

4280

name must match (the match is compiled to be case-sensitive)

4281

lineno is an integer that the line number where the

4282

warning occurred must match, or 0 to match all line

4283

numbers

4284

Since the Warning class is derived from the built-in

4285

Exception class, to turn a warning into an error we simply

4286

raise category(message).

4287

The warnings filter is initialized by -W options passed

4288

to the Python interpreter command line. The interpreter saves the

4289

arguments for all -W options without interpretation in

4290

sys.warnoptions; the warnings module parses these when

4291

it is first imported (invalid options are ignored, after printing a

4292

message to sys.stderr).

4293

</description>

4294

</group>

4295

4296

4297

<description>Issue a warning, or maybe ignore it or raise an exception. The

4298

category argument, if given, must be a warning category class

4299

(see above); it defaults to UserWarning. Alternatively

4300

message can be a Warning instance, in which case

4301

category will be ignored and message.__class__ will be used.

4302

In this case the message text will be str(message). This function

4303

raises an exception if the particular warning issued is changed

4304

into an error by the warnings filter see above. The stacklevel

4305

argument can be used by wrapper functions written in Python, like

4306

this:

4307

def deprecation(message):

4308

warnings.warn(message, DeprecationWarning, stacklevel=2)

4309

This makes the warning refer to deprecation()'s caller,

4310

rather than to the source of deprecation() itself (since

4311

the latter would defeat the purpose of the warning message).</description>

4312

<param name="message" optional="0">message</param><param name="category" optional="1">category</param><param name="stacklevel" optional="1">stacklevel</param>

4313

<insert>warn(message, [category], [stacklevel])</insert><dialog title="Insert warn">warn(%0, %1, %2)</dialog><info title="Info window"></info></function>

4314

4315

4316

<description>This is a low-level interface to the functionality of

4317

warn(), passing in explicitly the message, category,

4318

filename and line number, and optionally the module name and the

4319

registry (which should be the __warningregistry__ dictionary of

4320

the module). The module name defaults to the filename with .py

4321

stripped; if no registry is passed, the warning is never suppressed.

4322

message must be a string and category a subclass of

4323

Warning or message may be a Warning instance,

4324

in which case category will be ignored.</description>

4325

<param name="message" optional="0">message</param><param name="category" optional="0">category</param><param name="filename" optional="0">filename</param><param name="lineno" optional="0">lineno</param><param name="module" optional="1">module</param><param name="registry" optional="1">registry</param>

4326

<insert>warn_explicit(message, category, filename, lineno, [module], [registry])</insert><dialog title="Insert warn_explicit">warn_explicit(%0, %1, %2, %3, %4, %5)</dialog><info title="Info window"></info></function>

4327

4328

4329

<description>Write a warning to a file. The default implementation calls

4330

formatwarning(message, category, filename,

4331

lineno) and writes the resulting string to file, which

4332

defaults to sys.stderr. You may replace this function with an

4333

alternative implementation by assigning to

4334

warnings.showwarning.</description>

4335

<param name="message" optional="0">message</param><param name="category" optional="0">category</param><param name="filename" optional="0">filename</param><param name="lineno" optional="0">lineno</param><param name="file" optional="1">file</param>

4336

<insert>showwarning(message, category, filename, lineno, [file])</insert><dialog title="Insert showwarning">showwarning(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

4337

4338

4339

<description>Format a warning the standard way. This returns a string which may

4340

contain embedded newlines and ends in a newline.</description>

4341

<param name="message" optional="0">message</param><param name="category" optional="0">category</param><param name="filename" optional="0">filename</param><param name="lineno lineno" optional="0">lineno lineno</param>

4342

<insert>formatwarning(message, category, filename, lineno lineno)</insert><dialog title="Insert formatwarning">formatwarning(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

4343

4344

4345

<description>Insert an entry into the list of warnings filters. The entry is

4346

inserted at the front by default; if append is true, it is

4347

inserted at the end.

4348

This checks the types of the arguments, compiles the message and

4349

module regular expressions, and inserts them as a tuple in front

4350

of the warnings filter. Entries inserted later override entries

4351

inserted earlier, if both match a particular warning. Omitted

4352

arguments default to a value that matches everything.</description>

4353

<param name="action" optional="0">action</param><param name="message" optional="1">message</param><param name="category" optional="1">category</param><param name="module" optional="1">module</param><param name="lineno" optional="1">lineno</param><param name="append" optional="1">append</param>

4354

<insert>filterwarnings(action, [message], [category], [module], [lineno], [append])</insert><dialog title="Insert filterwarnings">filterwarnings(%0, %1, %2, %3, %4, %5)</dialog><info title="Info window"></info></function>

4355

4356

4357

<description>Reset the warnings filter. This discards the effect of all previous

4358

calls to filterwarnings(), including that of the

4359

-W command line options.</description>

4360

4361

<insert>resetwarnings()</insert><dialog title="Insert resetwarnings">resetwarnings()</dialog><info title="Info window"></info></function>

4362

4363

</group>

4364

</group>

4365

4366

<description>Base classes for interactive Python interpreters.

4367

The code module provides facilities to implement

4368

read-eval-print loops in Python. Two classes and convenience

4369

functions are included which can be used to build applications which

4370

provide an interactive interpreter prompt.

4371

</description>

4372

4373

<description>This class deals with parsing and interpreter state (the user's

4374

namespace); it does not deal with input buffering or prompting or

4375

input file naming (the filename is always passed in explicitly).

4376

The optional locals argument specifies the dictionary in

4377

which code will be executed; it defaults to a newly created

4378

dictionary with key '__name__' set to '__console__'

4379

and key '__doc__' set to None.</description>

4380

<param name="locals" optional="0">locals</param>

4381

<insert>InteractiveInterpreter(locals)</insert><dialog title="Insert InteractiveInterpreter">InteractiveInterpreter(%0)</dialog><info title="Info window"></info></function>

4382

4383

4384

<description>Closely emulate the behavior of the interactive Python interpreter.

4385

This class builds on InteractiveInterpreter and adds

4386

prompting using the familiar sys.ps1 and sys.ps2, and

4387

input buffering.</description>

4388

<param name="locals" optional="0">locals</param><param name="filename" optional="1">filename</param>

4389

<insert>InteractiveConsole(locals, [filename])</insert><dialog title="Insert InteractiveConsole">InteractiveConsole(%0, %1)</dialog><info title="Info window"></info></function>

4390

4391

4392

<description>Convenience function to run a read-eval-print loop. This creates a

4393

new instance of InteractiveConsole and sets readfunc

4394

to be used as the raw_input() method, if provided. If

4395

local is provided, it is passed to the

4396

InteractiveConsole constructor for use as the default

4397

namespace for the interpreter loop. The interact() method

4398

of the instance is then run with banner passed as the banner

4399

to use, if provided. The console object is discarded after use.</description>

4400

<param name="banner" optional="0">banner</param><param name="readfunc" optional="1">readfunc</param><param name="local" optional="1">local</param>

4401

<insert>interact(banner, [readfunc], [local])</insert><dialog title="Insert interact">interact(%0, %1, %2)</dialog><info title="Info window"></info></function>

4402

4403

4404

<description>This function is useful for programs that want to emulate Python's

4405

interpreter main loop (a.k.a. the read-eval-print loop). The tricky

4406

part is to determine when the user has entered an incomplete command

4407

that can be completed by entering more text (as opposed to a

4408

complete command or a syntax error). This function

4409

almost always makes the same decision as the real interpreter

4410

main loop.

4411

source is the source string; filename is the optional

4412

filename from which source was read, defaulting to '<input>';

4413

and symbol is the optional grammar start symbol, which should

4414

be either 'single' (the default) or 'eval'.

4415

Returns a code object (the same as compile(source,

4416

filename, symbol)) if the command is complete and

4417

valid; None if the command is incomplete; raises

4418

SyntaxError if the command is complete and contains a

4419

syntax error, or raises OverflowError or

4420

ValueError if the command cotains an invalid literal.</description>

4421

<param name="source" optional="0">source</param><param name="filename" optional="1">filename</param><param name="symbol" optional="1">symbol</param>

4422

<insert>compile_command(source, [filename], [symbol])</insert><dialog title="Insert compile_command">compile_command(%0, %1, %2)</dialog><info title="Info window"></info></function>

4423

4424

4425

4426

<description>Compile and run some source in the interpreter.

4427

Arguments are the same as for compile_command(); the

4428

default for filename is '<input>', and for

4429

symbol is 'single'. One several things can happen:

4430

The input is incorrect; compile_command() raised an

4431

exception (SyntaxError or OverflowError). A

4432

syntax traceback will be printed by calling the

4433

showsyntaxerror() method. runsource() returns

4434

False.

4435

The input is incomplete, and more input is required;

4436

compile_command() returned None.

4437

runsource() returns True.

4438

The input is complete; compile_command() returned a code

4439

object. The code is executed by calling the runcode() (which

4440

also handles run-time exceptions, except for SystemExit).

4441

runsource() returns False.

4442

The return value can be used to decide whether to use

4443

sys.ps1 or sys.ps2 to prompt the next line.</description>

4444

<param name="source" optional="0">source</param><param name="filename" optional="1">filename</param><param name="symbol" optional="1">symbol</param>

4445

<insert>runsource(source, [filename], [symbol])</insert><dialog title="Insert runsource">runsource(%0, %1, %2)</dialog><info title="Info window"></info></function>

4446

4447

4448

<description>Execute a code object.

4449

When an exception occurs, showtraceback() is called to

4450

display a traceback. All exceptions are caught except

4451

SystemExit, which is allowed to propagate.

4452

A note about KeyboardInterrupt: this exception may occur

4453

elsewhere in this code, and may not always be caught. The caller

4454

should be prepared to deal with it.</description>

4455

<param name="codecode" optional="0">codecode</param>

4456

<insert>runcode(codecode)</insert><dialog title="Insert runcode">runcode(%0)</dialog><info title="Info window"></info></function>

4457

4458

4459

<description>Display the syntax error that just occurred. This does not display

4460

a stack trace because there isn't one for syntax errors.

4461

If filename is given, it is stuffed into the exception instead

4462

of the default filename provided by Python's parser, because it

4463

always uses '<string>' when reading from a string.

4464

The output is written by the write() method.</description>

4465

<param name="filename" optional="0">filename</param>

4466

<insert>showsyntaxerror(filename)</insert><dialog title="Insert showsyntaxerror">showsyntaxerror(%0)</dialog><info title="Info window"></info></function>

4467

4468

4469

<description>Display the exception that just occurred. We remove the first stack

4470

item because it is within the interpreter object implementation.

4471

The output is written by the write() method.</description>

4472

4473

<insert>showtraceback()</insert><dialog title="Insert showtraceback">showtraceback()</dialog><info title="Info window"></info></function>

4474

4475

4476

<description>Write a string to the standard error stream (sys.stderr).

4477

Derived classes should override this to provide the appropriate output

4478

handling as needed.</description>

4479

<param name="datadata" optional="0">datadata</param>

4480

<insert>write(datadata)</insert><dialog title="Insert write">write(%0)</dialog><info title="Info window"></info></function>

4481

4482

</group>

4483

4484

<description>The InteractiveConsole class is a subclass of

4485

InteractiveInterpreter, and so offers all the methods of the

4486

interpreter objects as well as the following additions.

4487

</description>

4488

4489

<description>Closely emulate the interactive Python console.

4490

The optional banner argument specify the banner to print before the

4491

first interaction; by default it prints a banner similar to the one

4492

printed by the standard Python interpreter, followed by the class

4493

name of the console object in parentheses (so as not to confuse this

4494

with the real interpreter -- since it's so close!).</description>

4495

<param name="banner" optional="0">banner</param>

4496

<insert>interact(banner)</insert><dialog title="Insert interact">interact(%0)</dialog><info title="Info window"></info></function>

4497

4498

4499

<description>Push a line of source text to the interpreter.

4500

The line should not have a trailing newline; it may have internal

4501

newlines. The line is appended to a buffer and the interpreter's

4502

runsource() method is called with the concatenated contents

4503

of the buffer as source. If this indicates that the command was

4504

executed or invalid, the buffer is reset; otherwise, the command is

4505

incomplete, and the buffer is left as it was after the line was

4506

appended. The return value is True if more input is required,

4507

False if the line was dealt with in some way (this is the same as

4508

runsource()).</description>

4509

<param name="lineline" optional="0">lineline</param>

4510

<insert>push(lineline)</insert><dialog title="Insert push">push(%0)</dialog><info title="Info window"></info></function>

4511

4512

4513

<description>Remove any unhandled source text from the input buffer.</description>

4514

4515

<insert>resetbuffer()</insert><dialog title="Insert resetbuffer">resetbuffer()</dialog><info title="Info window"></info></function>

4516

4517

4518

<description>Write a prompt and read a line. The returned line does not include

4519

the trailing newline. When the user enters the key sequence,

4520

EOFError is raised. The base implementation uses the

4521

built-in function raw_input(); a subclass may replace this

4522

with a different implementation.</description>

4523

<param name="prompt" optional="0">prompt</param>

4524

<insert>raw_input(prompt)</insert><dialog title="Insert raw_input">raw_input(%0)</dialog><info title="Info window"></info></function>

4525

4526

</group>

4527

</group>

4528

4529

<description>% LaTeXed from excellent doc-string.

4530

Compile (possibly incomplete) Python code.

4531

The codeop module provides utilities upon which the Python

4532

read-eval-print loop can be emulated, as is done in the

4533

code module. As a result, you probably don't want to use

4534

the module directly; if you want to include such a loop in your

4535

program you probably want to use the code module instead.

4536

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

4537

`>>>~ or `...~' next.

4538

Remembering which future statements the user has entered, so subsequent input can be compiled with these in effect.

4539

The codeop module provides a way of doing each of these

4540

things, and a way of doing them both.

4541

To do just the former:

4542

</description>

4543

4544

<description>Tries to compile source, which should be a string of Python

4545

code and return a code object if source is valid

4546

Python code. In that case, the filename attribute of the code object

4547

will be filename, which defaults to '<input>'.

4548

Returns None if source is not valid Python

4549

code, but is a prefix of valid Python code.

4550

If there is a problem with source, an exception will be raised.

4551

SyntaxError is raised if there is invalid Python syntax,

4552

and OverflowError or ValueError if there is an

4553

invalid literal.

4554

The symbol argument determines whether source is compiled

4555

as a statement ('single', the default) or as an expression

4556

('eval'). Any other value will cause ValueError to be raised.

4557

Caveat:

4558

It is possible (but not likely) that the parser stops parsing

4559

with a successful outcome before reaching the end of the source;

4560

in this case, trailing symbols may be ignored instead of causing an

4561

error. For example, a backslash followed by two newlines may be

4562

followed by arbitrary garbage. This will be fixed once the API

4563

for the parser is better.</description>

4564

<param name="source" optional="0">source</param><param name="filename" optional="1">filename</param><param name="symbol" optional="1">symbol</param>

4565

<insert>compile_command(source, [filename], [symbol])</insert><dialog title="Insert compile_command">compile_command(%0, %1, %2)</dialog><info title="Info window"></info></function>

4566

4567

4568

<description>Instances of this class have __call__() methods indentical in

4569

signature to the built-in function compile(), but with the

4570

difference that if the instance compiles program text containing a

4571

__future__ statement, the instance 'remembers' and compiles

4572

all subsequent program texts with the statement in force.</description>

4573

4574

<insert>Compile()</insert><dialog title="Insert Compile">Compile()</dialog><info title="Info window"></info></function>

4575

4576

4577

<description>Instances of this class have __call__() methods identical in

4578

signature to compile_command(); the difference is that if

4579

the instance compiles program text containing a __future__

4580

statement, the instance 'remembers' and compiles all subsequent

4581

program texts with the statement in force.</description>

4582

4583

<insert>CommandCompiler()</insert><dialog title="Insert CommandCompiler">CommandCompiler()</dialog><info title="Info window"></info></function>

4584

4585

</group>

4586

4587

<description>Data pretty printer.

4588

The pprint module provides a capability to ``pretty-print''

4589

arbitrary Python data structures in a form which can be used as input

4590

to the interpreter. If the formatted structures include objects which

4591

are not fundamental Python types, the representation may not be

4592

loadable. This may be the case if objects such as files, sockets,

4593

classes, or instances are included, as well as many other builtin

4594

objects which are not representable as Python constants.

4595

The formatted representation keeps objects on a single line if it can,

4596

and breaks them onto multiple lines if they don't fit within the

4597

allowed width. Construct PrettyPrinter objects explicitly if

4598

you need to adjust the width constraint.

4599

The pprint module defines one class:

4600

% First the implementation class:

4601

</description>

4602

4603

<description>Construct a PrettyPrinter instance. This constructor

4604

understands several keyword parameters. An output stream may be set

4605

using the stream keyword; the only method used on the stream

4606

object is the file protocol's write() method. If not

4607

specified, the PrettyPrinter adopts sys.stdout. Three

4608

additional parameters may be used to control the formatted

4609

representation. The keywords are indent, depth, and

4610

width. The amount of indentation added for each recursive level

4611

is specified by indent; the default is one. Other values can

4612

cause output to look a little odd, but can make nesting easier to

4613

spot. The number of levels which may be printed is controlled by

4614

depth; if the data structure being printed is too deep, the next

4615

contained level is replaced by .... By default, there is no

4616

constraint on the depth of the objects being formatted. The desired

4617

output width is constrained using the width parameter; the

4618

default is eighty characters. If a structure cannot be formatted

4619

within the constrained width, a best effort will be made.

4620

>>> import pprint, sys

4621

>>> stuff = sys.path[:]

4622

>>> stuff.insert(0, stuff[:])

4623

>>> pp = pprint.PrettyPrinter(indent=4)

4624

>>> pp.pprint(stuff)

4625

[ [ '',

4626

'/usr/local/lib/python1.5',

4627

'/usr/local/lib/python1.5/test',

4628

'/usr/local/lib/python1.5/sunos5',

4629

'/usr/local/lib/python1.5/sharedmodules',

4630

'/usr/local/lib/python1.5/tkinter'],

4631

'',

4632

'/usr/local/lib/python1.5',

4633

'/usr/local/lib/python1.5/test',

4634

'/usr/local/lib/python1.5/sunos5',

4635

'/usr/local/lib/python1.5/sharedmodules',

4636

'/usr/local/lib/python1.5/tkinter']

4637

>>>

4638

>>> import parser

4639

>>> tup = parser.ast2tuple(

4640

... parser.suite(open('pprint.py').read()))[1][1][1]

4641

>>> pp = pprint.PrettyPrinter(depth=6)

4642

>>> pp.pprint(tup)

4643

(266, (267, (307, (287, (288, (...))))))

4644

</description>

4645

4646

<insert>PrettyPrinter(......)</insert><dialog title="Insert PrettyPrinter">PrettyPrinter(%0)</dialog><info title="Info window"></info></function>

4647

4648

4649

<description>Return the formatted representation of object as a string. indent,

4650

width and depth will be passed to the PrettyPrinter

4651

constructor as formatting parameters.

4652

Changed in version 2.4: The parameters indent, width and depth

4653

were added</description>

4654

<param name="object" optional="0">object</param><param name="indent" optional="1">indent</param><param name="width" optional="1">width</param><param name="depth" optional="1">depth</param>

4655

<insert>pformat(object, [indent], [width], [depth])</insert><dialog title="Insert pformat">pformat(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

4656

4657

4658

<description>Prints the formatted representation of object on stream,

4659

followed by a newline. If stream is omitted, sys.stdout

4660

is used. This may be used in the interactive interpreter instead of a

4661

print statement for inspecting values. indent,

4662

width and depth will be passed to the PrettyPrinter

4663

constructor as formatting parameters.

4664

>>> stuff = sys.path[:]

4665

>>> stuff.insert(0, stuff)

4666

>>> pprint.pprint(stuff)

4667

[<Recursion on list with id=869440>,

4668

'',

4669

'/usr/local/lib/python1.5',

4670

'/usr/local/lib/python1.5/test',

4671

'/usr/local/lib/python1.5/sunos5',

4672

'/usr/local/lib/python1.5/sharedmodules',

4673

'/usr/local/lib/python1.5/tkinter']

4674

Changed in version 2.4: The parameters indent, width and depth

4675

were added</description>

4676

<param name="object" optional="0">object</param><param name="stream" optional="1">stream</param><param name="indent" optional="1">indent</param><param name="width" optional="1">width</param><param name="depth" optional="1">depth</param>

4677

<insert>pprint(object, [stream], [indent], [width], [depth])</insert><dialog title="Insert pprint">pprint(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

4678

4679

4680

<description>Determine if the formatted representation of object is

4681

``readable,'' or can be used to reconstruct the value using

4682

eval()eval. This always returns false for

4683

recursive objects.

4684

>>> pprint.isreadable(stuff)

4685

False

4686

</description>

4687

<param name="objectobject" optional="0">objectobject</param>

4688

<insert>isreadable(objectobject)</insert><dialog title="Insert isreadable">isreadable(%0)</dialog><info title="Info window"></info></function>

4689

4690

4691

<description>Determine if object requires a recursive representation.</description>

4692

<param name="objectobject" optional="0">objectobject</param>

4693

<insert>isrecursive(objectobject)</insert><dialog title="Insert isrecursive">isrecursive(%0)</dialog><info title="Info window"></info></function>

4694

4695

4696

<description>Return a string representation of object, protected against

4697

recursive data structures. If the representation of object

4698

exposes a recursive entry, the recursive reference will be represented

4699

as <Recursion on typename with id=number>. The

4700

representation is not otherwise formatted.</description>

4701

<param name="objectobject" optional="0">objectobject</param>

4702

<insert>saferepr(objectobject)</insert><dialog title="Insert saferepr">saferepr(%0)</dialog><info title="Info window"></info></function>

4703

4704

4705

4706

<description>Return the formatted representation of object. This takes into

4707

Account the options passed to the PrettyPrinter constructor.</description>

4708

<param name="objectobject" optional="0">objectobject</param>

4709

<insert>pformat(objectobject)</insert><dialog title="Insert pformat">pformat(%0)</dialog><info title="Info window"></info></function>

4710

4711

4712

<description>Print the formatted representation of object on the configured

4713

stream, followed by a newline.</description>

4714

<param name="objectobject" optional="0">objectobject</param>

4715

<insert>pprint(objectobject)</insert><dialog title="Insert pprint">pprint(%0)</dialog><info title="Info window"></info></function>

4716

4717

4718

<description>Determine if the formatted representation of the object is

4719

``readable,'' or can be used to reconstruct the value using

4720

eval()eval. Note that this returns false for

4721

recursive objects. If the depth parameter of the

4722

PrettyPrinter is set and the object is deeper than allowed,

4723

this returns false.</description>

4724

<param name="objectobject" optional="0">objectobject</param>

4725

<insert>isreadable(objectobject)</insert><dialog title="Insert isreadable">isreadable(%0)</dialog><info title="Info window"></info></function>

4726

4727

4728

<description>Determine if the object requires a recursive representation.</description>

4729

<param name="objectobject" optional="0">objectobject</param>

4730

<insert>isrecursive(objectobject)</insert><dialog title="Insert isrecursive">isrecursive(%0)</dialog><info title="Info window"></info></function>

4731

4732

4733

<description>Returns three values: the formatted version of object as a

4734

string, a flag indicating whether the result is readable, and a flag

4735

indicating whether recursion was detected. The first argument is the

4736

object to be presented. The second is a dictionary which contains the

4737

id() of objects that are part of the current presentation

4738

context (direct and indirect containers for object that are

4739

affecting the presentation) as the keys; if an object needs to be

4740

presented which is already represented in context, the third

4741

return value should be true. Recursive calls to the format()

4742

method should add additionaly entries for containers to this

4743

dictionary. The fourth argument, maxlevels, gives the requested

4744

limit to recursion; this will be 0 if there is no requested

4745

limit. This argument should be passed unmodified to recursive calls.

4746

The fourth argument, level gives the current level; recursive

4747

calls should be passed a value less than that of the current call.

4748

New in version 2.3</description>

4749

<param name="object" optional="0">object</param><param name="context" optional="0">context</param><param name="maxlevels" optional="0">maxlevels</param><param name="level level" optional="0">level level</param>

4750

<insert>format(object, context, maxlevels, level level)</insert><dialog title="Insert format">format(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

4751

4752

</group>

4753

</group>

4754

4755

<description>Alternate repr() implementation with size limits.

4756

The repr module provides a means for producing object

4757

representations with limits on the size of the resulting strings.

4758

This is used in the Python debugger and may be useful in other

4759

contexts as well.

4760

This module provides a class, an instance, and a function:

4761

</description>

4762

4763

<description>Class which provides formatting services useful in implementing

4764

functions similar to the built-in repr(); size limits for different object types are added to avoid the generation of

4765

representations which are excessively long.</description>

4766

4767

4768

4769

4770

<description>This is the repr() method of aRepr. It returns a

4771

string similar to that returned by the built-in function of the same name, but with limits on most sizes.</description>

4772

<param name="objobj" optional="0">objobj</param>

4773

<insert>repr(objobj)</insert><dialog title="Insert repr">repr(%0)</dialog><info title="Info window"></info></function>

4774

4775

4776

<description>Repr instances provide several members which can be used to

4777

provide size limits for the representations of different object types, and methods which format specific object types.

4778

{maxlevel}

4779

Depth limit on the creation of recursive representations. The

4780

default is 6.

4781

{maxdict}

4782

maxlist

4783

maxtuple

4784

Limits on the number of entries represented for the named object

4785

type. The default for maxdict is 4, for the others, 6.

4786

{maxlong}

4787

Maximum number of characters in the representation for a long

4788

integer. Digits are dropped from the middle. The default is

4789

40.

4790

{maxstring}

4791

Limit on the number of characters in the representation of the

4792

string. Note that the ``normal'' representation of the string is

4793

used as the character source: if escape sequences are needed in the

4794

representation, these may be mangled when the representation is

4795

shortened. The default is 30.

4796

{maxother}

4797

This limit is used to control the size of object types for which no

4798

specific formatting method is available on the Repr object.

4799

It is applied in a similar manner as maxstring. The

4800

default is 20.

4801

</description>

4802

4803

<description>The equivalent to the built-in repr() that uses the

4804

formatting imposed by the instance.</description>

4805

<param name="objobj" optional="0">objobj</param>

4806

<insert>repr(objobj)</insert><dialog title="Insert repr">repr(%0)</dialog><info title="Info window"></info></function>

4807

4808

4809

<description>Recursive implementation used by repr(). This uses the

4810

type of obj to determine which formatting method to call,

4811

passing it obj and level. The type-specific methods

4812

should call repr1() to perform recursive formatting, with

4813

level - 1 for the value of level in the recursive call.</description>

4814

<param name="obj" optional="0">obj</param><param name="level level" optional="0">level level</param>

4815

<insert>repr1(obj, level level)</insert><dialog title="Insert repr1">repr1(%0, %1)</dialog><info title="Info window"></info></function>

4816

4817

</group>

4818

4819

</group>

4820

</group>

4821

4822

<description>Interface to the creation of runtime implementation objects.

4823

The new module allows an interface to the interpreter object

4824

creation functions. This is for use primarily in marshal-type functions,

4825

when a new object needs to be created ``magically'' and not by using the

4826

regular creation functions. This module provides a low-level interface

4827

to the interpreter, so care must be exercised when using this module.

4828

The new module defines the following functions:

4829

</description>

4830

4831

<description>This function creates an instance of class with dictionary

4832

dict without calling the __init__() constructor. If

4833

dict is omitted or None, a new, empty dictionary is

4834

created for the new instance. Note that there are no guarantees that

4835

the object will be in a consistent state.</description>

4836

<param name="class" optional="0">class</param><param name="dict" optional="1">dict</param>

4837

<insert>instance(class, [dict])</insert><dialog title="Insert instance">instance(%0, %1)</dialog><info title="Info window"></info></function>

4838

4839

4840

<description>This function will return a method object, bound to instance, or

4841

unbound if instance is None. function must be

4842

callable.</description>

4843

<param name="function" optional="0">function</param><param name="instance" optional="0">instance</param><param name="class class" optional="0">class class</param>

4844

<insert>instancemethod(function, instance, class class)</insert><dialog title="Insert instancemethod">instancemethod(%0, %1, %2)</dialog><info title="Info window"></info></function>

4845

4846

4847

<description>Returns a (Python) function with the given code and globals. If

4848

name is given, it must be a string or None. If it is a

4849

string, the function will have the given name, otherwise the function

4850

name will be taken from code.co_name. If

4851

argdefs is given, it must be a tuple and will be used to

4852

determine the default values of parameters.</description>

4853

<param name="code" optional="0">code</param><param name="globals" optional="0">globals</param><param name="name" optional="1">name</param><param name="argdefs" optional="1">argdefs</param>

4854

<insert>function(code, globals, [name], [argdefs])</insert><dialog title="Insert function">function(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

4855

4856

4857

<description>This function is an interface to the PyCode_New() C

4858

function.

4859

%XXX This is still undocumented!!!!!!!!!!!</description>

4860

<param name="argcount" optional="0">argcount</param><param name="nlocals" optional="0">nlocals</param><param name="stacksize" optional="0">stacksize</param><param name="flags" optional="0">flags</param><param name="codestring" optional="0">codestring</param><param name="constants" optional="0">constants</param><param name="names" optional="0">names</param><param name="varnames" optional="0">varnames</param><param name="filename" optional="0">filename</param><param name="name" optional="0">name</param><param name="firstlineno" optional="0">firstlineno</param><param name="lnotab

4861

lnotab" optional="0">lnotab

4862

lnotab</param>

4863

<insert>code(argcount, nlocals, stacksize, flags, codestring, constants, names, varnames, filename, name, firstlineno, lnotab

4864

lnotab)</insert><dialog title="Insert code">code(%0, %1, %2, %3, %4, %5, %6, %7, %8, %9, %10, %11)</dialog><info title="Info window"></info></function>

4865

4866

4867

<description>This function returns a new module object with name name.

4868

name must be a string.</description>

4869

<param name="namename" optional="0">namename</param>

4870

<insert>module(namename)</insert><dialog title="Insert module">module(%0)</dialog><info title="Info window"></info></function>

4871

4872

4873

<description>This function returns a new class object, with name name, derived

4874

from baseclasses (which should be a tuple of classes) and with

4875

namespace dict.</description>

4876

<param name="name" optional="0">name</param><param name="baseclasses" optional="0">baseclasses</param><param name="dict dict" optional="0">dict dict</param>

4877

<insert>classobj(name, baseclasses, dict dict)</insert><dialog title="Insert classobj">classobj(%0, %1, %2)</dialog><info title="Info window"></info></function>

4878

4879

</group>

4880

4881

</group>

4882

4883

</group>

4884

4885

</group>

4886

4887

</group>

4888

4889

</group>

4890

</group>

4891

4892

4893

<description>Common string operations.

4894

This module defines some constants useful for checking character

4895

classes and some useful string functions. See the module

4896

rere for string functions based on regular

4897

expressions.

4898

The constants defined in this module are:

4899

{ascii_letters}

4900

The concatenation of the ascii_lowercase and

4901

ascii_uppercase constants described below. This value is

4902

not locale-dependent.

4903

{ascii_lowercase}

4904

The lowercase letters 'abcdefghijklmnopqrstuvwxyz'. This

4905

value is not locale-dependent and will not change.

4906

{ascii_uppercase}

4907

The uppercase letters 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. This

4908

value is not locale-dependent and will not change.

4909

{digits}

4910

The string '0123456789'.

4911

{hexdigits}

4912

The string '0123456789abcdefABCDEF'.

4913

{letters}

4914

The concatenation of the strings lowercase and

4915

uppercase described below. The specific value is

4916

locale-dependent, and will be updated when

4917

locale.setlocale() is called.

4918

{lowercase}

4919

A string containing all the characters that are considered lowercase

4920

letters. On most systems this is the string

4921

'abcdefghijklmnopqrstuvwxyz'. Do not change its definition ---

4922

the effect on the routines upper() and

4923

swapcase() is undefined. The specific value is

4924

locale-dependent, and will be updated when

4925

locale.setlocale() is called.

4926

{octdigits}

4927

The string '01234567'.

4928

{punctuation}

4929

String of ASCII characters which are considered punctuation

4930

characters in the C locale.

4931

{printable}

4932

String of characters which are considered printable. This is a

4933

combination of digits, letters,

4934

punctuation, and whitespace.

4935

{uppercase}

4936

A string containing all the characters that are considered uppercase

4937

letters. On most systems this is the string

4938

'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. Do not change its definition ---

4939

the effect on the routines lower() and

4940

swapcase() is undefined. The specific value is

4941

locale-dependent, and will be updated when

4942

locale.setlocale() is called.

4943

{whitespace}

4944

A string containing all characters that are considered whitespace.

4945

On most systems this includes the characters space, tab, linefeed,

4946

return, formfeed, and vertical tab. Do not change its definition ---

4947

the effect on the routines strip() and split()

4948

is undefined.

4949

Many of the functions provided by this module are also defined as

4950

methods of string and Unicode objects; see ``String Methods'' (section

4951

string-methods) for more information on those.

4952

The functions defined in this module are:

4953

</description>

4954

4955

<description>2.0{Use the float() built-in function.}

4956

Convert a string to a floating point number. The string must have

4957

the standard syntax for a floating point literal in Python,

4958

optionally preceded by a sign (+ or -). Note that

4959

this behaves identical to the built-in function

4960

float()float when passed a string.

4961

When passing in a string, values for NaN</description>

4962

4963

4964

4965

4966

<description>2.0{Use the int() built-in function.}

4967

Convert string s to an integer in the given base. The

4968

string must consist of one or more digits, optionally preceded by a

4969

sign (+ or -). The base defaults to 10. If it

4970

is 0, a default base is chosen depending on the leading characters

4971

of the string (after stripping the sign): 0x or 0X

4972

means 16, 0 means 8, anything else means 10. If base

4973

is 16, a leading 0x or 0X is always accepted, though

4974

not required. This behaves identically to the built-in function

4975

int() when passed a string. (Also note: for a more

4976

flexible interpretation of numeric literals, use the built-in

4977

function eval()eval.)</description>

4978

4979

4980

4981

4982

<description>2.0{Use the long() built-in function.}

4983

Convert string s to a long integer in the given base.

4984

The string must consist of one or more digits, optionally preceded

4985

by a sign (+ or -). The base argument has the

4986

same meaning as for atoi(). A trailing l or

4987

L is not allowed, except if the base is 0. Note that when

4988

invoked without base or with base set to 10, this

4989

behaves identical to the built-in function

4990

long()long when passed a string.</description>

4991

4992

4993

4994

4995

<description>Return a copy of word with only its first character capitalized.</description>

4996

<param name="wordword" optional="0">wordword</param>

4997

<insert>capitalize(wordword)</insert><dialog title="Insert capitalize">capitalize(%0)</dialog><info title="Info window"></info></function>

4998

4999

5000

<description>Split the argument into words using split(), capitalize

5001

each word using capitalize(), and join the capitalized

5002

words using join(). Note that this replaces runs of

5003

whitespace characters by a single space, and removes leading and

5004

trailing whitespace.</description>

5005

5006

<insert>capwords(ss)</insert><dialog title="Insert capwords">capwords(%0)</dialog><info title="Info window"></info></function>

5007

5008

5009

<description>Expand tabs in a string, i.e. them by one or more spaces,

5010

depending on the current column and the given tab size. The column

5011

number is reset to zero after each newline occurring in the string.

5012

This doesn't understand other non-printing characters or escape

5013

sequences. The tab size defaults to 8.</description>

5014

<param name="s" optional="0">s</param><param name="tabsize" optional="1">tabsize</param>

5015

<insert>expandtabs(s, [tabsize])</insert><dialog title="Insert expandtabs">expandtabs(%0, %1)</dialog><info title="Info window"></info></function>

5016

5017

5018

<description>Return the lowest index in s where the substring sub is

5019

found such that sub is wholly contained in

5020

s[start:end]. Return -1 on failure.

5021

Defaults for start and end and interpretation of

5022

negative values is the same as for slices.</description>

5023

<param name="s" optional="0">s</param><param name="sub" optional="0">sub</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

5024

<insert>find(s, sub, [start], [end])</insert><dialog title="Insert find">find(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

5025

5026

5027

<description>Like find() but find the highest index.</description>

5028

<param name="s" optional="0">s</param><param name="sub" optional="0">sub</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

5029

<insert>rfind(s, sub, [start], [end])</insert><dialog title="Insert rfind">rfind(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

5030

5031

5032

<description>Like find() but raise ValueError when the

5033

substring is not found.</description>

5034

<param name="s" optional="0">s</param><param name="sub" optional="0">sub</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

5035

<insert>index(s, sub, [start], [end])</insert><dialog title="Insert index">index(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

5036

5037

5038

<description>Like rfind() but raise ValueError when the

5039

substring is not found.</description>

5040

<param name="s" optional="0">s</param><param name="sub" optional="0">sub</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

5041

<insert>rindex(s, sub, [start], [end])</insert><dialog title="Insert rindex">rindex(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

5042

5043

5044

<description>Return the number of (non-overlapping) occurrences of substring

5045

sub in string s[start:end].

5046

Defaults for start and end and interpretation of

5047

negative values are the same as for slices.</description>

5048

<param name="s" optional="0">s</param><param name="sub" optional="0">sub</param><param name="start" optional="1">start</param><param name="end" optional="1">end</param>

5049

<insert>count(s, sub, [start], [end])</insert><dialog title="Insert count">count(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

5050

5051

5052

<description>Return a copy of s, but with upper case letters converted to

5053

lower case.</description>

5054

5055

<insert>lower(ss)</insert><dialog title="Insert lower">lower(%0)</dialog><info title="Info window"></info></function>

5056

5057

5058

<description>Return a translation table suitable for passing to

5059

translate() or regex.compile(), that will map

5060

each character in from into the character at the same position

5061

in to; from and to must have the same length.

5062

Don't use strings derived from lowercase

5063

and uppercase as arguments; in some locales, these don't have

5064

the same length. For case conversions, always use

5065

lower() and upper().</description>

5066

5067

<insert>maketrans(from, to to)</insert><dialog title="Insert maketrans">maketrans(%0, %1)</dialog><info title="Info window"></info></function>

5068

5069

5070

<description>Return a list of the words of the string s. If the optional

5071

second argument sep is absent or None, the words are

5072

separated by arbitrary strings of whitespace characters (space, tab, newline, return, formfeed). If the second argument sep is

5073

present and not None, it specifies a string to be used as the word separator. The returned list will then have one more item

5074

than the number of non-overlapping occurrences of the separator in

5075

the string. The optional third argument maxsplit defaults to

5076

0. If it is nonzero, at most maxsplit number of splits occur,

5077

and the remainder of the string is returned as the final element of

5078

the list (thus, the list will have at most maxsplit+1

5079

elements).</description>

5080

<param name="s" optional="0">s</param><param name="sep" optional="1">sep</param><param name="maxsplit" optional="1">maxsplit</param>

5081

<insert>split(s, [sep], [maxsplit])</insert><dialog title="Insert split">split(%0, %1, %2)</dialog><info title="Info window"></info></function>

5082

5083

5084

<description>Return a list of the words of the string s, scanning s

5085

from the end. To all intents and purposes, the resulting list of

5086

words is the same as returned by split(), except when the

5087

optional third argument maxsplit is explicitly specified and

5088

nonzero. When maxsplit is nonzero, at most maxsplit

5089

number of splits -- the rightmost ones -- occur, and the remainder

5090

of the string is returned as the first element of the list (thus, the

5091

list will have at most maxsplit+1 elements).

5092

New in version 2.4</description>

5093

<param name="s" optional="0">s</param><param name="sep" optional="1">sep</param><param name="maxsplit" optional="1">maxsplit</param>

5094

<insert>rsplit(s, [sep], [maxsplit])</insert><dialog title="Insert rsplit">rsplit(%0, %1, %2)</dialog><info title="Info window"></info></function>

5095

5096

5097

<description>This function behaves identically to split(). (In the

5098

past, split() was only used with one argument, while

5099

splitfields() was only used with two arguments.)</description>

5100

<param name="s" optional="0">s</param><param name="sep" optional="1">sep</param><param name="maxsplit" optional="1">maxsplit</param>

5101

<insert>splitfields(s, [sep], [maxsplit])</insert><dialog title="Insert splitfields">splitfields(%0, %1, %2)</dialog><info title="Info window"></info></function>

5102

5103

5104

<description>Concatenate a list or tuple of words with intervening occurrences of sep. The default value for sep is a single space

5105

character. It is always true that

5106

string.join(string.split(s, sep), sep)

5107

equals s.</description>

5108

<param name="words" optional="0">words</param><param name="sep" optional="1">sep</param>

5109

<insert>join(words, [sep])</insert><dialog title="Insert join">join(%0, %1)</dialog><info title="Info window"></info></function>

5110

5111

5112

<description>This function behaves identically to join(). (In the past, join() was only used with one argument, while

5113

joinfields() was only used with two arguments.)

5114

Note that there is no joinfields() method on string

5115

objects; use the join() method instead.</description>

5116

<param name="words" optional="0">words</param><param name="sep" optional="1">sep</param>

5117

<insert>joinfields(words, [sep])</insert><dialog title="Insert joinfields">joinfields(%0, %1)</dialog><info title="Info window"></info></function>

5118

5119

5120

<description>Return a copy of the string with leading characters removed. If

5121

chars is omitted or None, whitespace characters are

5122

removed. If given and not None, chars must be a string;

5123

the characters in the string will be stripped from the beginning of

5124

the string this method is called on.

5125

Changed in version 2.2.3: The chars parameter was added. The chars

5126

parameter cannot be passed in earlier 2.2 versions</description>

5127

<param name="s" optional="0">s</param><param name="chars" optional="1">chars</param>

5128

<insert>lstrip(s, [chars])</insert><dialog title="Insert lstrip">lstrip(%0, %1)</dialog><info title="Info window"></info></function>

5129

5130

5131

<description>Return a copy of the string with trailing characters removed. If

5132

chars is omitted or None, whitespace characters are

5133

removed. If given and not None, chars must be a string;

5134

the characters in the string will be stripped from the end of the

5135

string this method is called on.

5136

Changed in version 2.2.3: The chars parameter was added. The chars

5137

parameter cannot be passed in 2.2 versions</description>

5138

<param name="s" optional="0">s</param><param name="chars" optional="1">chars</param>

5139

<insert>rstrip(s, [chars])</insert><dialog title="Insert rstrip">rstrip(%0, %1)</dialog><info title="Info window"></info></function>

5140

5141

5142

<description>Return a copy of the string with leading and trailing characters

5143

removed. If chars is omitted or None, whitespace

5144

characters are removed. If given and not None, chars

5145

must be a string; the characters in the string will be stripped from

5146

the both ends of the string this method is called on.

5147

Changed in version 2.2.3: The chars parameter was added. The chars

5148

parameter cannot be passed in earlier 2.2 versions</description>

5149

<param name="s" optional="0">s</param><param name="chars" optional="1">chars</param>

5150

<insert>strip(s, [chars])</insert><dialog title="Insert strip">strip(%0, %1)</dialog><info title="Info window"></info></function>

5151

5152

5153

<description>Return a copy of s, but with lower case letters

5154

converted to upper case and vice versa.</description>

5155

5156

<insert>swapcase(ss)</insert><dialog title="Insert swapcase">swapcase(%0)</dialog><info title="Info window"></info></function>

5157

5158

5159

<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

5160

character value, indexed by its ordinal.</description>

5161

<param name="s" optional="0">s</param><param name="table" optional="0">table</param><param name="deletechars" optional="1">deletechars</param>

5162

<insert>translate(s, table, [deletechars])</insert><dialog title="Insert translate">translate(%0, %1, %2)</dialog><info title="Info window"></info></function>

5163

5164

5165

<description>Return a copy of s, but with lower case letters converted to

5166

upper case.</description>

5167

5168

<insert>upper(ss)</insert><dialog title="Insert upper">upper(%0)</dialog><info title="Info window"></info></function>

5169

5170

5171

<description>rjust{s, width}

5172

center{s, width}

5173

These functions respectively left-justify, right-justify and center

5174

a string in a field of given width. They return a string that is at

5175

least width characters wide, created by padding the string

5176

s with spaces until the given width on the right, left or both

5177

sides. The string is never truncated.</description>

5178

<param name="s" optional="0">s</param><param name="width width" optional="0">width width</param>

5179

<insert>ljust(s, width width)</insert><dialog title="Insert ljust">ljust(%0, %1)</dialog><info title="Info window"></info></function>

5180

5181

5182

<description>Pad a numeric string on the left with zero digits until the given

5183

width is reached. Strings starting with a sign are handled

5184

correctly.</description>

5185

<param name="s" optional="0">s</param><param name="width width" optional="0">width width</param>

5186

<insert>zfill(s, width width)</insert><dialog title="Insert zfill">zfill(%0, %1)</dialog><info title="Info window"></info></function>

5187

5188

5189

<description>Return a copy of string str with all occurrences of substring

5190

old replaced by new. If the optional argument

5191

maxreplace is given, the first maxreplace occurrences are

5192

replaced.</description>

5193

<param name="str" optional="0">str</param><param name="old" optional="0">old</param><param name="new" optional="0">new</param><param name="maxreplace" optional="1">maxreplace</param>

5194

<insert>replace(str, old, new, [maxreplace])</insert><dialog title="Insert replace">replace(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

5195

5196

</group>

5197

5198

<description>Regular expression search and match operations with a

5199

Perl-style expression syntax.

5200

This module provides regular expression matching operations similar to

5201

those found in Perl. Regular expression pattern strings may not

5202

contain null bytes, but can specify the null byte using the

5203

\number notation. Both patterns and strings to be

5204

searched can be Unicode strings as well as 8-bit strings. The

5205

re module is always available.

5206

Regular expressions use the backslash character (\) to

5207

indicate special forms or to allow special characters to be used

5208

without invoking their special meaning. This collides with Python's

5209

usage of the same character for the same purpose in string literals;

5210

for example, to match a literal backslash, one might have to write

5211

'\e\e' as the pattern string, because the regular expression

5212

must be \e, and each backslash must be expressed as

5213

\e inside a regular Python string literal.

5214

The solution is to use Python's raw string notation for regular

5215

expression patterns; backslashes are not handled in any special way in

5216

a string literal prefixed with r. So r"\n" is a

5217

two-character string containing \ and n,

5218

while "\n" is a one-character string containing a newline.

5219

Usually patterns will be expressed in Python code using this raw

5220

string notation.

5221

See also Mastering Regular Expressions - Book on regular expressions

5222

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

5223

patterns in great detail.

5224

</description>

5225

5226

<description>A regular expression (or RE) specifies a set of strings that matches

5227

it; the functions in this module let you check if a particular string

5228

matches a given regular expression (or if a given regular expression

5229

matches a particular string, which comes down to the same thing).

5230

Regular expressions can be concatenated to form new regular

5231

expressions; if A and B are both regular expressions,

5232

then AB is also a regular expression. In general, if a string

5233

p matches A and another string q matches B,

5234

the string pq will match AB. This holds unless A or

5235

B contain low precedence operations; boundary conditions between

5236

A and B; or have numbered group references. Thus, complex

5237

expressions can easily be constructed from simpler primitive

5238

expressions like the ones described here. For details of the theory

5239

and implementation of regular expressions, consult the Friedl book

5240

referenced above, or almost any textbook about compiler construction.

5241

A brief explanation of the format of regular expressions follows. For

5242

further information and a gentler presentation, consult the Regular

5243

Expression HOWTO, accessible from http://www.python.org/doc/howto/.

5244

Regular expressions can contain both special and ordinary characters.

5245

Most ordinary characters, like A, a, or

5246

0, are the simplest regular expressions; they simply match

5247

themselves. You can concatenate ordinary characters, so last

5248

matches the string 'last'. (In the rest of this section, we'll

5249

write RE's in this special style, usually without quotes, and

5250

strings to be matched 'in single quotes'.)

5251

Some characters, like | or (, are special.

5252

Special characters either stand for classes of ordinary characters, or

5253

affect how the regular expressions around them are interpreted.

5254

The special characters are:

5255

{}{ 0.7in 0.65in}

5256

[.] (Dot.) In the default mode, this matches any

5257

character except a newline. If the DOTALL flag has been

5258

specified, this matches any character including a newline.

5259

[] (Caret.) Matches the start of the

5260

string, and in MULTILINE mode also matches immediately

5261

after each newline.

5262

[$] Matches the end of the string or just before the

5263

newline at the end of the string, and in MULTILINE mode

5264

also matches before a newline. foo matches both 'foo' and

5265

'foobar', while the regular expression foo$ matches only

5266

'foo'. More interestingly, searching for foo.$ in

5267

'foo1 nfoo2 n' matches 'foo2' normally,

5268

but 'foo1' in MULTILINE mode.

5269

[*] Causes the resulting RE to

5270

match 0 or more repetitions of the preceding RE, as many repetitions

5271

as are possible. ab* will

5272

match 'a', 'ab', or 'a' followed by any number of 'b's.

5273

[+] Causes the

5274

resulting RE to match 1 or more repetitions of the preceding RE.

5275

ab+ will match 'a' followed by any non-zero number of 'b's; it

5276

will not match just 'a'.

5277

[?] Causes the resulting RE to

5278

match 0 or 1 repetitions of the preceding RE. ab? will

5279

match either 'a' or 'ab'.

5280

[*?, +?, ??] The *,

5281

+, and ? qualifiers are all greedy; they

5282

match as much text as possible. Sometimes this behaviour isn't

5283

desired; if the RE <.*> is matched against

5284

'<H1>title</H1>', it will match the entire string, and not just

5285

'<H1>'. Adding ? after the qualifier makes it

5286

perform the match in non-greedy or minimal fashion; as

5287

few characters as possible will be matched. Using .*?

5288

in the previous expression will match only '<H1>'.

5289

[{m}]

5290

Specifies that exactly m copies of the previous RE should be

5291

matched; fewer matches cause the entire RE not to match. For example,

5292

a{6} will match exactly six a characters, but

5293

not five.

5294

[{m,n}] Causes the resulting RE to match from

5295

m to n repetitions of the preceding RE, attempting to

5296

match as many repetitions as possible. For example, a{3,5}

5297

will match from 3 to 5 a characters. Omitting m

5298

specifies a lower bound of zero, and omitting n specifies an infinite upper bound. As an

5299

example, a{4,}b will match aaaab or a thousand

5300

a characters followed by a b, but not aaab.

5301

The comma may not be omitted or the modifier would be confused with

5302

the previously described form.

5303

[{m,n}?] Causes the resulting RE to

5304

match from m to n repetitions of the preceding RE,

5305

attempting to match as few repetitions as possible. This is

5306

the non-greedy version of the previous qualifier. For example, on the

5307

6-character string 'aaaaaa', a{3,5} will match 5

5308

a characters, while a{3,5}? will only match 3

5309

characters.

5310

[\] Either escapes special characters (permitting

5311

you to match characters like *, ?, and so

5312

forth), or signals a special sequence; special sequences are discussed

5313

below.

5314

If you're not using a raw string to

5315

express the pattern, remember that Python also uses the

5316

backslash as an escape sequence in string literals; if the escape

5317

sequence isn't recognized by Python's parser, the backslash and

5318

subsequent character are included in the resulting string. However,

5319

if Python would recognize the resulting sequence, the backslash should

5320

be repeated twice. This is complicated and hard to understand, so

5321

it's highly recommended that you use raw strings for all but the

5322

simplest expressions.

5323

[[]] Used to indicate a set of characters. Characters can

5324

be listed individually, or a range of characters can be indicated by

5325

giving two characters and separating them by a -. Special

5326

characters are not active inside sets. For example, [akm]

5327

will match any of the characters a, k,

5328

m, or $; [a-z]

5329

will match any lowercase letter, and [a-zA-Z0-9] matches any

5330

letter or digit. Character classes such as \w or \S

5331

(defined below) are also acceptable inside a range. If you want to

5332

include a ] or a - inside a set, precede it with a

5333

backslash, or place it as the first character. The

5334

pattern []] will match ']', for example.

5335

You can match the characters not within a range by complementing

5336

the set. This is indicated by including a

5337

as the first character of the set;

5338

elsewhere will simply match the

5339

character. For example,

5340

[{}5] will match

5341

any character except 5, and

5342

[] will match any character

5343

except .

5344

[|]A|B, where A and B can be arbitrary REs,

5345

creates a regular expression that will match either A or B. An

5346

arbitrary number of REs can be separated by the | in this

5347

way. This can be used inside groups (see below) as well. As the target

5348

string is scanned, REs separated by | are tried from left to

5349

right. When one pattern completely matches, that branch is accepted.

5350

This means that once A matches, B will not be tested further,

5351

even if it would produce a longer overall match. In other words, the

5352

| operator is never greedy. To match a literal |,

5353

use \, or enclose it inside a character class, as in [|].

5354

[(...)] Matches whatever regular expression is inside the

5355

parentheses, and indicates the start and end of a group; the contents

5356

of a group can be retrieved after a match has been performed, and can

5357

be matched later in the string with the \number special

5358

sequence, described below. To match the literals ( or

5359

), use \ or \, or enclose them

5360

inside a character class: [(] [)].

5361

[(?...)] This is an extension notation (a ?

5362

following a ( is not meaningful otherwise). The first

5363

character after the ?

5364

determines what the meaning and further syntax of the construct is.

5365

Extensions usually do not create a new group;

5366

(?P<name>...) is the only exception to this rule.

5367

Following are the currently supported extensions.

5368

[(?iLmsux)] (One or more letters from the set i,

5369

L, m, s, u,

5370

x.) The group matches the empty string; the letters set

5371

the corresponding flags (re.I, re.L,

5372

re.M, re.S, re.U, re.X)

5373

for the entire regular expression. This is useful if you wish to

5374

include the flags as part of the regular expression, instead of

5375

passing a flag argument to the compile() function.

5376

Note that the (?x) flag changes how the expression is parsed.

5377

It should be used first in the expression string, or after one or more

5378

whitespace characters. If there are non-whitespace characters before

5379

the flag, the results are undefined.

5380

[(?:...)] A non-grouping version of regular parentheses.

5381

Matches whatever regular expression is inside the parentheses, but the

5382

substring matched by the

5383

group cannot be retrieved after performing a match or

5384

referenced later in the pattern.

5385

[(?P<name>...)] Similar to regular parentheses, but

5386

the substring matched by the group is accessible via the symbolic group

5387

name name. Group names must be valid Python identifiers, and

5388

each group name must be defined only once within a regular expression. A

5389

symbolic group is also a numbered group, just as if the group were not

5390

named. So the group named 'id' in the example above can also be

5391

referenced as the numbered group 1.

5392

For example, if the pattern is

5393

(?P<id>[a-zA-Z_]\w*), the group can be referenced by its

5394

name in arguments to methods of match objects, such as

5395

m.group('id') or m.end('id'), and also by name in

5396

pattern text (for example, (?P=id)) and replacement text

5397

(such as \g<id>).

5398

[(?P=name)] Matches whatever text was matched by the

5399

earlier group named name.

5400

[(?)] A comment; the contents of the parentheses are

5401

simply ignored.

5402

[(?=...)] Matches if ... matches next, but doesn't

5403

consume any of the string. This is called a lookahead assertion. For

5404

example, Isaac (?=Asimov) will match 'Isaac~' only if it's

5405

followed by 'Asimov'.

5406

[(?!...)] Matches if ... doesn't match next. This

5407

is a negative lookahead assertion. For example,

5408

Isaac (?!Asimov) will match 'Isaac~' only if it's not

5409

followed by 'Asimov'.

5410

[(?<=...)] Matches if the current position in the string

5411

is preceded by a match for ... that ends at the current

5412

position. This is called a positive lookbehind assertion.

5413

(?<=abc)def will find a match in abcdef, since the

5414

lookbehind will back up 3 characters and check if the contained

5415

pattern matches. The contained pattern must only match strings of

5416

some fixed length, meaning that abc or a|b are

5417

allowed, but a* and a{3,4} are not. Note that

5418

patterns which start with positive lookbehind assertions will never

5419

match at the beginning of the string being searched; you will most

5420

likely want to use the search() function rather than the

5421

match() function:

5422

>>> import re

5423

>>> m = re.search('(?<=abc)def', 'abcdef')

5424

>>> m.group(0)

5425

'def'

5426

This example looks for a word following a hyphen:

5427

>>> m = re.search('(?<=-)+', 'spam-egg')

5428

>>> m.group(0)

5429

'egg'

5430

[(?<!...)] Matches if the current position in the string

5431

is not preceded by a match for .... This is called a

5432

negative lookbehind assertion. Similar to positive lookbehind

5433

assertions, the contained pattern must only match strings of some

5434

fixed length. Patterns which start with negative lookbehind

5435

assertions may match at the beginning of the string being searched.

5436

[(?(id/name)yes-pattern|no-pattern)] Will try to match

5437

with yes-pattern if the group with given id or name

5438

exists, and with no-pattern if it doesn't. |no-pattern

5439

is optional and can be omitted. For example, (<)?(\w+@\w+(?:\.\w+)+)(?(1)>) is a poor email matching

5440

pattern, which will match with '<user@host.com>' as well as

5441

'user@host.com', but not with '<user@host.com'.

5442

New in version 2.4

5443

The special sequences consist of \ and a character from the

5444

list below. If the ordinary character is not on the list, then the

5445

resulting RE will match the second character. For example,

5446

\$ matches the character $.

5447

{}{ 0.7in 0.65in}

5448

[\number] Matches the contents of the group of the

5449

same number. Groups are numbered starting from 1. For example,

5450

(.+) \1 matches 'the the' or '55 55', but not

5451

'the end' (note

5452

the space after the group). This special sequence can only be used to

5453

match one of the first 99 groups. If the first digit of number

5454

is 0, or number is 3 octal digits long, it will not be interpreted

5455

as a group match, but as the character with octal value number.

5456

Inside the [ and ] of a character class, all numeric

5457

escapes are treated as characters.

5458

[\A] Matches only at the start of the string.

5459

[\b] Matches the empty string, but only at the

5460

beginning or end of a word. A word is defined as a sequence of

5461

alphanumeric or underscore characters, so the end of a word is indicated by

5462

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

5463

values of the UNICODE and LOCALE flags. Inside a character

5464

range, \b represents the backspace character, for compatibility

5465

with Python's string literals.

5466

[\B] Matches the empty string, but only when it is not

5467

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.

5468

[\d]Matches any decimal digit; this is

5469

equivalent to the set [0-9].

5470

[\D]Matches any non-digit character; this is

5471

equivalent to the set [{}0-9].

5472

[\s]Matches any whitespace character; this is

5473

equivalent to the set [ \t\n\r\f\v].

5474

[\S]Matches any non-whitespace character; this is

5475

equivalent to the set [ t\n\r\f\v].

5476

[\w]When the LOCALE and UNICODE

5477

flags are not specified, matches any alphanumeric character and the

5478

underscore; this is equivalent to the set

5479

[a-zA-Z0-9_]. With LOCALE, it will match the set

5480

[0-9_] plus whatever characters are defined as alphanumeric for

5481

the current locale. If UNICODE is set, this will match the

5482

characters [0-9_] plus whatever is classified as alphanumeric

5483

in the Unicode character properties database.

5484

[\W]When the LOCALE and UNICODE

5485

flags are not specified, matches any non-alphanumeric character; this

5486

is equivalent to the set [{}a-zA-Z0-9_]. With

5487

LOCALE, it will match any character not in the set

5488

[0-9_], and not defined as alphanumeric for the current locale.

5489

If UNICODE is set, this will match anything other than

5490

[0-9_] and characters marked as alphanumeric in the Unicode

5491

character properties database.

5492

[\Z]Matches only at the end of the string.

5493

Most of the standard escapes supported by Python string literals are

5494

also accepted by the regular expression parser:

5495

Octal escapes are included in a limited form: If the first digit is a

5496

0, or if there are three octal digits, it is considered an octal

5497

escape. Otherwise, it is a group reference.

5498

% Note the lack of a period in the section title; it causes problems

5499

% with readers of the GNU info version. See http://www.python.org/sf/581414.

5500

</description>

5501

</group>

5502

5503

<description>Python offers two different primitive operations based on regular

5504

expressions: match and search. If you are accustomed to Perl's

5505

semantics, the search operation is what you're looking for. See the

5506

search() function and corresponding method of compiled

5507

regular expression objects.

5508

Note that match may differ from search using a regular expression

5509

beginning with :

5510

matches only at the

5511

start of the string, or in MULTILINE mode also immediately

5512

following a newline. The ``match'' operation succeeds only if the

5513

pattern matches at the start of the string regardless of mode, or at

5514

the starting position given by the optional pos argument

5515

regardless of whether a newline precedes it.

5516

% Examples from Tim Peters:

5517

re.compile("a").match("ba", 1) # succeeds

5518

re.compile("^a").search("ba", 1) # fails; 'a' not at start

5519

re.compile("^a").search("", 1) # fails; 'a' not at start

5520

re.compile("^a", re.M).search("", 1) # succeeds

5521

re.compile("^a", re.M).search("ba", 1) # fails; no preceding </description>

5522

</group>

5523

5524

<description>Contents of Module re

5525

The module defines the following functions and constants, and an exception:

5526

</description>

5527

5528

<description>Compile a regular expression pattern into a regular expression

5529

object, which can be used for matching using its match() and

5530

search() methods, described below.

5531

The expression's behaviour can be modified by specifying a

5532

flags value. Values can be any of the following variables,

5533

combined using bitwise OR (the | operator).

5534

The sequence

5535

prog = re.compile(pat)

5536

result = prog.match(str)

5537

is equivalent to

5538

result = re.match(pat, str)

5539

but the version using compile() is more efficient when the

5540

expression will be used several times in a single program.

5541

%(The compiled version of the last pattern passed to

5542

%re.match() or re.search() is cached, so

5543

%programs that use only a single regular expression at a time needn't

5544

%worry about compiling regular expressions.)</description>

5545

<param name="pattern" optional="0">pattern</param><param name="flags" optional="1">flags</param>

5546

<insert>compile(pattern, [flags])</insert><dialog title="Insert compile">compile(%0, %1)</dialog><info title="Info window"></info></function>

5547

5548

5549

<description>Scan through string looking for a location where the regular

5550

expression pattern produces a match, and return a

5551

corresponding MatchObject instance.

5552

Return None if no

5553

position in the string matches the pattern; note that this is

5554

different from finding a zero-length match at some point in the string.</description>

5555

<param name="pattern" optional="0">pattern</param><param name="string" optional="0">string</param><param name="flags" optional="1">flags</param>

5556

<insert>search(pattern, string, [flags])</insert><dialog title="Insert search">search(%0, %1, %2)</dialog><info title="Info window"></info></function>

5557

5558

5559

<description>If zero or more characters at the beginning of string match

5560

the regular expression pattern, return a corresponding

5561

MatchObject instance. Return None if the string does not

5562

match the pattern; note that this is different from a zero-length

5563

match.

5564

If you want to locate a match anywhere in

5565

string, use search() instead.</description>

5566

<param name="pattern" optional="0">pattern</param><param name="string" optional="0">string</param><param name="flags" optional="1">flags</param>

5567

<insert>match(pattern, string, [flags])</insert><dialog title="Insert match">match(%0, %1, %2)</dialog><info title="Info window"></info></function>

5568

5569

5570

<description>Split string by the occurrences of pattern. If

5571

capturing parentheses are used in pattern, then the text of all

5572

groups in the pattern are also returned as part of the resulting list.

5573

If maxsplit is nonzero, at most maxsplit splits

5574

occur, and the remainder of the string is returned as the final

5575

element of the list. (Incompatibility note: in the original Python

5576

1.5 release, maxsplit was ignored. This has been fixed in

5577

later releases.)

5578

>>> re.split('+', 'Words, words, words.')

5579

['Words', 'words', 'words', '']

5580

>>> re.split('(+)', 'Words, words, words.')

5581

['Words', ', ', 'words', ', ', 'words', '.', '']

5582

>>> re.split('+', 'Words, words, words.', 1)

5583

['Words', 'words, words.']

5584

This function combines and extends the functionality of

5585

the old regsub.split() and regsub.splitx().</description>

5586

<param name="pattern" optional="0">pattern</param><param name="string" optional="0">string</param><param name="maxsplit" optional="1" default=" 0">maxsplit</param>

5587

<insert>split(pattern, string, [maxsplit= 0])</insert><dialog title="Insert split">split(%0, %1, %2)</dialog><info title="Info window"></info></function>

5588

5589

5590

<description>Return a list of all non-overlapping matches of pattern in

5591

string. If one or more groups are present in the pattern,

5592

return a list of groups; this will be a list of tuples if the

5593

pattern has more than one group. Empty matches are included in the

5594

result unless they touch the beginning of another match.

5595

New in version 1.5.2</description>

5596

<param name="pattern" optional="0">pattern</param><param name="string string" optional="0">string string</param>

5597

<insert>findall(pattern, string string)</insert><dialog title="Insert findall">findall(%0, %1)</dialog><info title="Info window"></info></function>

5598

5599

5600

<description>Return an iterator over all non-overlapping matches for the RE

5601

pattern in string. For each match, the iterator returns

5602

a match object. Empty matches are included in the result unless they

5603

touch the beginning of another match.

5604

New in version 2.2</description>

5605

<param name="pattern" optional="0">pattern</param><param name="string string" optional="0">string string</param>

5606

<insert>finditer(pattern, string string)</insert><dialog title="Insert finditer">finditer(%0, %1)</dialog><info title="Info window"></info></function>

5607

5608

5609

<description>Return the string obtained by replacing the leftmost non-overlapping

5610

occurrences of pattern in string by the replacement

5611

repl. If the pattern isn't found, string is returned

5612

unchanged. repl can be a string or a function; if it is a

5613

string, any backslash escapes in it are processed. That is,

5614

\n is converted to a single newline character, \r

5615

is converted to a linefeed, and so forth. Unknown escapes such as

5616

\j are left alone. Backreferences, such as \, are

5617

replaced with the substring matched by group 6 in the pattern. For

5618

example:

5619

>>> re.sub(r'def+([a-zA-Z_][a-zA-Z_0-9]*)**'static PyObject*_)',

5620

... 'def myfunc():')

5621

'static PyObject*_myfunc(void)'

5622

If repl is a function, it is called for every non-overlapping

5623

occurrence of pattern. The function takes a single match

5624

object argument, and returns the replacement string. For example:

5625

>>> def dashrepl(matchobj):

5626

.... if matchobj.group(0) == '-': return ' '

5627

.... else: return '-'

5628

>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')

5629

'pro--gram files'

5630

The pattern may be a string or an RE object; if you need to specify

5631

regular expression flags, you must use a RE object, or use embedded

5632

modifiers in a pattern; for example, sub("(?i)b+", "x", "bbbb

5633

BBBB") returns 'x x'.

5634

The optional argument count is the maximum number of pattern

5635

occurrences to be replaced; count must be a non-negative

5636

integer. If omitted or zero, all occurrences will be replaced.

5637

Empty matches for the pattern are replaced only when not adjacent to

5638

a previous match, so sub('x*', '-', 'abc') returns

5639

'-a-b-c-'.

5640

In addition to character escapes and backreferences as described

5641

above, \g<name> will use the substring matched by the group

5642

named name, as defined by the (?P<name>...) syntax.

5643

\g<number> uses the corresponding group number;

5644

\g<2> is therefore equivalent to \2, but isn't

5645

ambiguous in a replacement such as \g<2>0. \20

5646

would be interpreted as a reference to group 20, not a reference to

5647

group 2 followed by the literal character 0. The

5648

backreference \g<0> substitutes in the entire substring

5649

matched by the R</description>

5650

<param name="pattern" optional="0">pattern</param><param name="repl" optional="0">repl</param><param name="string" optional="0">string</param><param name="count" optional="1">count</param>

5651

<insert>sub(pattern, repl, string, [count])</insert><dialog title="Insert sub">sub(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

5652

5653

5654

<description>Perform the same operation as sub(), but return a tuple

5655

(new_string, number_of_subs_made).</description>

5656

<param name="pattern" optional="0">pattern</param><param name="repl" optional="0">repl</param><param name="string" optional="0">string</param><param name="count" optional="1">count</param>

5657

<insert>subn(pattern, repl, string, [count])</insert><dialog title="Insert subn">subn(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

5658

5659

5660

<description>Return string with all non-alphanumerics backslashed; this is

5661

useful if you want to match an arbitrary literal string that may have

5662

regular expression metacharacters in it.</description>

5663

<param name="stringstring" optional="0">stringstring</param>

5664

<insert>escape(stringstring)</insert><dialog title="Insert escape">escape(%0)</dialog><info title="Info window"></info></function>

5665

5666

</group>

5667

5668

<description>Compiled regular expression objects support the following methods and

5669

attributes:

5670

</description>

5671

5672

<description>If zero or more characters at the beginning of string match

5673

this regular expression, return a corresponding

5674

MatchObject instance. Return None if the string does not

5675

match the pattern; note that this is different from a zero-length

5676

match.

5677

If you want to locate a match anywhere in

5678

string, use search() instead.

5679

The optional second parameter pos gives an index in the string

5680

where the search is to start; it defaults to 0. This is not

5681

completely equivalent to slicing the string; the

5682

'' pattern

5683

character matches at the real beginning of the string and at positions

5684

just after a newline, but not necessarily at the index where the search

5685

is to start.

5686

The optional parameter endpos limits how far the string will

5687

be searched; it will be as if the string is endpos characters

5688

long, so only the characters from pos to endpos -

5689

1 will be searched for a match. If endpos is less than

5690

pos, no match will be found, otherwise, if rx is a

5691

compiled regular expression object,

5692

rx.match(string, 0, 50) is equivalent to

5693

rx.match(string[:50], 0).</description>

5694

<param name="string" optional="0">string</param><param name="pos" optional="1">pos</param><param name="endpos" optional="1">endpos</param>

5695

<insert>match(string, [pos], [endpos])</insert><dialog title="Insert match">match(%0, %1, %2)</dialog><info title="Info window"></info></function>

5696

5697

5698

<description>Scan through string looking for a location where this regular

5699

expression produces a match, and return a

5700

corresponding MatchObject instance. Return None if no

5701

position in the string matches the pattern; note that this is

5702

different from finding a zero-length match at some point in the string.

5703

The optional pos and endpos parameters have the same

5704

meaning as for the match() method.</description>

5705

<param name="string" optional="0">string</param><param name="pos" optional="1">pos</param><param name="endpos" optional="1">endpos</param>

5706

<insert>search(string, [pos], [endpos])</insert><dialog title="Insert search">search(%0, %1, %2)</dialog><info title="Info window"></info></function>

5707

5708

5709

<description>Identical to the split() function, using the compiled pattern.</description>

5710

<param name="string" optional="0">string</param><param name="maxsplit" optional="1" default=" 0">maxsplit</param>

5711

<insert>split(string, [maxsplit= 0])</insert><dialog title="Insert split">split(%0, %1)</dialog><info title="Info window"></info></function>

5712

5713

5714

<description>Identical to the findall() function, using the compiled pattern.</description>

5715

<param name="stringstring" optional="0">stringstring</param>

5716

<insert>findall(stringstring)</insert><dialog title="Insert findall">findall(%0)</dialog><info title="Info window"></info></function>

5717

5718

5719

<description>Identical to the finditer() function, using the compiled pattern.</description>

5720

<param name="stringstring" optional="0">stringstring</param>

5721

<insert>finditer(stringstring)</insert><dialog title="Insert finditer">finditer(%0)</dialog><info title="Info window"></info></function>

5722

5723

5724

<description>Identical to the sub() function, using the compiled pattern.</description>

5725

<param name="repl" optional="0">repl</param><param name="string" optional="0">string</param><param name="count" optional="1" default=" 0">count</param>

5726

<insert>sub(repl, string, [count= 0])</insert><dialog title="Insert sub">sub(%0, %1, %2)</dialog><info title="Info window"></info></function>

5727

5728

5729

<description>Identical to the subn() function, using the compiled pattern.</description>

5730

<param name="repl" optional="0">repl</param><param name="string" optional="0">string</param><param name="count" optional="1" default=" 0">count</param>

5731

<insert>subn(repl, string, [count= 0])</insert><dialog title="Insert subn">subn(%0, %1, %2)</dialog><info title="Info window"></info></function>

5732

5733

</group>

5734

5735

<description>MatchObject instances support the following methods and

5736

attributes:

5737

</description>

5738

5739

<description>Return the string obtained by doing backslash substitution on the

5740

template string template, as done by the sub() method.

5741

Escapes such as \n are converted to the appropriate

5742

characters, and numeric backreferences (\1, \2) and

5743

named backreferences (\g<1>, \g<name>) are replaced

5744

by the contents of the corresponding group.</description>

5745

<param name="templatetemplate" optional="0">templatetemplate</param>

5746

<insert>expand(templatetemplate)</insert><dialog title="Insert expand">expand(%0)</dialog><info title="Info window"></info></function>

5747

5748

5749

<description>Returns one or more subgroups of the match. If there is a single

5750

argument, the result is a single string; if there are

5751

multiple arguments, the result is a tuple with one item per argument.

5752

Without arguments, group1 defaults to zero (the whole match

5753

is returned).

5754

If a groupN argument is zero, the corresponding return value is the

5755

entire matching string; if it is in the inclusive range [1..99], it is

5756

the string matching the corresponding parenthesized group. If a

5757

group number is negative or larger than the number of groups defined

5758

in the pattern, an IndexError exception is raised.

5759

If a group is contained in a part of the pattern that did not match,

5760

the corresponding result is None. If a group is contained in a

5761

part of the pattern that matched multiple times, the last match is

5762

returned.

5763

If the regular expression uses the (?P<name>...) syntax,

5764

the groupN arguments may also be strings identifying groups by

5765

their group name. If a string argument is not used as a group name in

5766

the pattern, an IndexError exception is raised.

5767

A moderately complicated example:

5768

m = re.match(r"(?P<int>+)*)", '3.14')

5769

After performing this match, m.group(1) is '3', as is

5770

m.group('int'), and m.group(2) is '14'.</description>

5771

<param name="group1" optional="0">group1</param><param name="moreargs" optional="1">moreargs</param>

5772

<insert>group(group1, [moreargs])</insert><dialog title="Insert group">group(%0, %1)</dialog><info title="Info window"></info></function>

5773

5774

5775

<description>Return a tuple containing all the subgroups of the match, from 1 up to

5776

however many groups are in the pattern. The default argument is

5777

used for groups that did not participate in the match; it defaults to

5778

None. (Incompatibility note: in the original Python 1.5

5779

release, if the tuple was one element long, a string would be returned

5780

instead. In later versions (from 1.5.1 on), a singleton tuple is

5781

returned in such cases.)</description>

5782

<param name="default" optional="0">default</param>

5783

<insert>groups(default)</insert><dialog title="Insert groups">groups(%0)</dialog><info title="Info window"></info></function>

5784

5785

5786

<description>Return a dictionary containing all the named subgroups of the

5787

match, keyed by the subgroup name. The default argument is

5788

used for groups that did not participate in the match; it defaults to

5789

None.</description>

5790

<param name="default" optional="0">default</param>

5791

<insert>groupdict(default)</insert><dialog title="Insert groupdict">groupdict(%0)</dialog><info title="Info window"></info></function>

5792

5793

5794

<description>end{group}

5795

Return the indices of the start and end of the substring

5796

matched by group; group defaults to zero (meaning the whole

5797

matched substring).

5798

Return -1 if group exists but

5799

did not contribute to the match. For a match object

5800

m, and a group g that did contribute to the match, the

5801

substring matched by group g (equivalent to

5802

m.group(g)) is

5803

m.string[m.start(g):m.end(g)]

5804

Note that

5805

m.start(group) will equal m.end(group) if

5806

group matched a null string. For example, after m =

5807

re.search('b(c?)', 'cba'), m.start(0) is 1,

5808

m.end(0) is 2, m.start(1) and

5809

m.end(1) are both 2, and m.start(2) raises

5810

an IndexError exception.</description>

5811

<param name="group" optional="0">group</param>

5812

<insert>start(group)</insert><dialog title="Insert start">start(%0)</dialog><info title="Info window"></info></function>

5813

5814

5815

<description>For MatchObject m, return the 2-tuple

5816

(m.start(group), m.end(group)).

5817

Note that if group did not contribute to the match, this is

5818

(-1, -1). Again, group defaults to zero.</description>

5819

<param name="group" optional="0">group</param>

5820

<insert>span(group)</insert><dialog title="Insert span">span(%0)</dialog><info title="Info window"></info></function>

5821

5822

</group>

5823

5824

</group>

5825

</group>

5826

5827

<description>Interpret strings as packed binary data.

5828

packing{binary}{data}

5829

This module performs conversions between Python values and C

5830

structs represented as Python strings. It uses format strings

5831

(explained below) as compact descriptions of the lay-out of the C

5832

structs and the intended conversion to/from Python values. This can

5833

be used in handling binary data stored in files or from network

5834

connections, among other sources.

5835

The module defines the following exception and functions:

5836

{error}

5837

Exception raised on various occasions; argument is a string

5838

describing what is wrong.

5839

</description>

5840

5841

<description>Return a string containing the values

5842

v1, v2, ... packed according to the given

5843

format. The arguments must match the values required by the format

5844

exactly.</description>

5845

<param name="fmt" optional="0">fmt</param><param name="v1" optional="0">v1</param><param name="v2" optional="0">v2</param><param name="ldots" optional="0">ldots</param>

5846

<insert>pack(fmt, v1, v2, ldots)</insert><dialog title="Insert pack">pack(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

5847

5848

5849

<description>Unpack the string (presumably packed by pack(fmt,

5850

...)) according to the given format. The result is a

5851

tuple even if it contains exactly one item. The string must contain

5852

exactly the amount of data required by the format

5853

(len(string) must equal calcsize(fmt)).</description>

5854

<param name="fmt" optional="0">fmt</param><param name="string string" optional="0">string string</param>

5855

<insert>unpack(fmt, string string)</insert><dialog title="Insert unpack">unpack(%0, %1)</dialog><info title="Info window"></info></function>

5856

5857

5858

<description>Return the size of the struct (and hence of the string)

5859

corresponding to the given format.</description>

5860

<param name="fmtfmt" optional="0">fmtfmt</param>

5861

<insert>calcsize(fmtfmt)</insert><dialog title="Insert calcsize">calcsize(%0)</dialog><info title="Info window"></info></function>

5862

5863

</group>

5864

5865

<description>Helpers for computing differences between objects.

5866

% LaTeXification by Fred L. Drake, Jr. <fdrake@acm.org>.

5867

New in version 2.1

5868

{SequenceMatcher}

5869

This is a flexible class for comparing pairs of sequences of any

5870

type, so long as the sequence elements are hashable. The basic

5871

algorithm predates, and is a little fancier than, an algorithm

5872

published in the late 1980's by Ratcliff and Obershelp under the

5873

hyperbolic name ``gestalt pattern matching.'' The idea is to find

5874

the longest contiguous matching subsequence that contains no

5875

``junk'' elements (the Ratcliff and Obershelp algorithm doesn't

5876

address junk). The same idea is then applied recursively to the

5877

pieces of the sequences to the left and to the right of the matching

5878

subsequence. This does not yield minimal edit sequences, but does

5879

tend to yield matches that ``look right'' to people.

5880

Timing: The basic Ratcliff-Obershelp algorithm is cubic

5881

time in the worst case and quadratic time in the expected case.

5882

SequenceMatcher is quadratic time for the worst case and has

5883

expected-case behavior dependent in a complicated way on how many

5884

elements the sequences have in common; best case time is linear.

5885

{Differ}

5886

This is a class for comparing sequences of lines of text, and

5887

producing human-readable differences or deltas. Differ uses

5888

SequenceMatcher both to compare sequences of lines, and to

5889

compare sequences of characters within similar (near-matching)

5890

lines.

5891

Each line of a Differ delta begins with a two-letter code:

5892

{l|l}{code}{Code}{Meaning}

5893

'- '{line unique to sequence 1}

5894

'+ '{line unique to sequence 2}

5895

' '{line common to both sequences}

5896

'? '{line not present in either input sequence}

5897

Lines beginning with `?~' attempt to guide the eye to

5898

intraline differences, and were not present in either input

5899

sequence. These lines can be confusing if the sequences contain tab

5900

characters.

5901

</description>

5902

5903

<description>Compare a and b (lists of strings); return a

5904

delta (a generator generating the delta lines) in context diff

5905

format.

5906

Context diffs are a compact way of showing just the lines that have

5907

changed plus a few lines of context. The changes are shown in a

5908

before/after style. The number of context lines is set by n

5909

which defaults to three.

5910

By default, the diff control lines (those with *** or ---)

5911

are created with a trailing newline. This is helpful so that inputs created

5912

from file.readlines() result in diffs that are suitable for use

5913

with file.writelines() since both the inputs and outputs have

5914

trailing newlines.

5915

For inputs that do not have trailing newlines, set the lineterm

5916

argument to "" so that the output will be uniformly newline free.

5917

The context diff format normally has a header for filenames and

5918

modification times. Any or all of these may be specified using strings for

5919

fromfile, tofile, fromfiledate, and tofiledate.

5920

The modification times are normally expressed in the format returned by

5921

time.ctime(). If not specified, the strings default to blanks.

5922

Tools/scripts/diff.py is a command-line front-end for this

5923

function.

5924

New in version 2.3</description>

5925

<param name="a" optional="0">a</param><param name="b" optional="0">b</param><param name="fromfile" optional="1">fromfile</param><param name="tofile" optional="1">tofile</param><param name="fromfiledate" optional="1">fromfiledate</param><param name="tofiledate" optional="1">tofiledate</param><param name="n" optional="1">n</param><param name="lineterm" optional="1">lineterm</param>

5926

<insert>context_diff(a, b, [fromfile], [tofile], [fromfiledate], [tofiledate], [n], [lineterm])</insert><dialog title="Insert context_diff">context_diff(%0, %1, %2, %3, %4, %5, %6, %7)</dialog><info title="Info window"></info></function>

5927

5928

5929

<description>Return a list of the best ``good enough'' matches. word is a

5930

sequence for which close matches are desired (typically a string),

5931

and possibilities is a list of sequences against which to

5932

match word (typically a list of strings).

5933

Optional argument n (default 3) is the maximum number

5934

of close matches to return; n must be greater than 0.

5935

Optional argument cutoff (default 0.6) is a float in

5936

the range [0, 1]. Possibilities that don't score at least that

5937

similar to word are ignored.

5938

The best (no more than n) matches among the possibilities are

5939

returned in a list, sorted by similarity score, most similar first.

5940

>>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])

5941

['apple', 'ape']

5942

>>> import keyword

5943

>>> get_close_matches('wheel', keyword.kwlist)

5944

['while']

5945

>>> get_close_matches('apple', keyword.kwlist)

5946

[]

5947

>>> get_close_matches('accept', keyword.kwlist)

5948

['except']

5949

</description>

5950

<param name="word" optional="0">word</param><param name="possibilities" optional="0">possibilities</param><param name="n" optional="1">n</param><param name="cutoff" optional="1">cutoff</param>

5951

<insert>get_close_matches(word, possibilities, [n], [cutoff])</insert><dialog title="Insert get_close_matches">get_close_matches(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

5952

5953

5954

<description>Compare a and b (lists of strings); return a

5955

Differ-style delta (a generator generating the delta lines).

5956

Optional keyword parameters linejunk and charjunk are

5957

for filter functions (or None):

5958

linejunk: A function that accepts a single string

5959

argument, and returns true if the string is junk, or false if not.

5960

The default is (None), starting with Python 2.3. Before then,

5961

the default was the module-level function

5962

IS_LINE_JUNK(), which filters out lines without visible

5963

characters, except for at most one pound character (#).

5964

As of Python 2.3, the underlying SequenceMatcher class

5965

does a dynamic analysis of which lines are so frequent as to

5966

constitute noise, and this usually works better than the pre-2.3

5967

default.

5968

charjunk: A function that accepts a character (a string of

5969

length 1), and returns if the character is junk, or false if not.

5970

The default is module-level function IS_CHARACTER_JUNK(),

5971

which filters out whitespace characters (a blank or tab; note: bad

5972

idea to include newline in this!).

5973

Tools/scripts/ndiff.py is a command-line front-end to this

5974

function.

5975

>>> diff = ndiff('one'.splitlines(1),

5976

... 'ore'.splitlines(1))

5977

>>> print ''.join(diff),

5978

- one

5979

? ^

5980

+ ore

5981

? ^

5982

- two

5983

- three

5984

? -

5985

+ tree

5986

+ emu

5987

</description>

5988

<param name="a" optional="0">a</param><param name="b" optional="0">b</param><param name="linejunk" optional="1">linejunk</param><param name="charjunk" optional="1">charjunk</param>

5989

<insert>ndiff(a, b, [linejunk], [charjunk])</insert><dialog title="Insert ndiff">ndiff(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

5990

5991

5992

<description>Return one of the two sequences that generated a delta.

5993

Given a sequence produced by Differ.compare() or

5994

ndiff(), extract lines originating from file 1 or 2

5995

(parameter which), stripping off line prefixes.

5996

Example:

5997

>>> diff = ndiff('one'.splitlines(1),

5998

... 'ore'.splitlines(1))

5999

>>> diff = list(diff) # materialize the generated delta into a list

6000

>>> print ''.join(restore(diff, 1)),

6001

one

6002

two

6003

three

6004

>>> print ''.join(restore(diff, 2)),

6005

ore

6006

tree

6007

emu

6008

</description>

6009

<param name="sequence" optional="0">sequence</param><param name="which which" optional="0">which which</param>

6010

<insert>restore(sequence, which which)</insert><dialog title="Insert restore">restore(%0, %1)</dialog><info title="Info window"></info></function>

6011

6012

6013

<description>Compare a and b (lists of strings); return a

6014

delta (a generator generating the delta lines) in unified diff

6015

format.

6016

Unified diffs are a compact way of showing just the lines that have

6017

changed plus a few lines of context. The changes are shown in a

6018

inline style (instead of separate before/after blocks). The number

6019

of context lines is set by n which defaults to three.

6020

By default, the diff control lines (those with ---, +++,

6021

or @@) are created with a trailing newline. This is helpful so

6022

that inputs created from file.readlines() result in diffs

6023

that are suitable for use with file.writelines() since both

6024

the inputs and outputs have trailing newlines.

6025

For inputs that do not have trailing newlines, set the lineterm

6026

argument to "" so that the output will be uniformly newline free.

6027

The context diff format normally has a header for filenames and

6028

modification times. Any or all of these may be specified using strings for

6029

fromfile, tofile, fromfiledate, and tofiledate.

6030

The modification times are normally expressed in the format returned by

6031

time.ctime(). If not specified, the strings default to blanks.

6032

Tools/scripts/diff.py is a command-line front-end for this

6033

function.

6034

New in version 2.3</description>

6035

<param name="a" optional="0">a</param><param name="b" optional="0">b</param><param name="fromfile" optional="1">fromfile</param><param name="tofile" optional="1">tofile</param><param name="fromfiledate" optional="1">fromfiledate</param><param name="tofiledate" optional="1">tofiledate</param><param name="n" optional="1">n</param><param name="lineterm" optional="1">lineterm</param>

6036

<insert>unified_diff(a, b, [fromfile], [tofile], [fromfiledate], [tofiledate], [n], [lineterm])</insert><dialog title="Insert unified_diff">unified_diff(%0, %1, %2, %3, %4, %5, %6, %7)</dialog><info title="Info window"></info></function>

6037

6038

6039

<description>Return true for ignorable lines. The line line is ignorable

6040

if line is blank or contains a single #,

6041

otherwise it is not ignorable. Used as a default for parameter

6042

linejunk in ndiff() before Python 2.3.</description>

6043

<param name="lineline" optional="0">lineline</param>

6044

<insert>IS_LINE_JUNK(lineline)</insert><dialog title="Insert IS_LINE_JUNK">IS_LINE_JUNK(%0)</dialog><info title="Info window"></info></function>

6045

6046

6047

<description>Return true for ignorable characters. The character ch is

6048

ignorable if ch is a space or tab, otherwise it is not

6049

ignorable. Used as a default for parameter charjunk in

6050

ndiff().</description>

6051

6052

<insert>IS_CHARACTER_JUNK(chch)</insert><dialog title="Insert IS_CHARACTER_JUNK">IS_CHARACTER_JUNK(%0)</dialog><info title="Info window"></info></function>

6053

6054

6055

<description>The SequenceMatcher class has this constructor:

6056

</description>

6057

6058

<description>Optional argument isjunk must be None (the default) or

6059

a one-argument function that takes a sequence element and returns

6060

true if and only if the element is ``junk'' and should be ignored.

6061

Passing None for b is equivalent to passing

6062

lambda x: 0; in other words, no elements are ignored. For

6063

example, pass:

6064

lambda x: x in " "

6065

if you're comparing lines as sequences of characters, and don't want

6066

to synch up on blanks or hard tabs.

6067

The optional arguments a and b are sequences to be

6068

compared; both default to empty strings. The elements of both

6069

sequences must be hashable.</description>

6070

<param name="isjunk" optional="0">isjunk</param><param name="a" optional="1">a</param><param name="b" optional="1">b</param>

6071

<insert>SequenceMatcher(isjunk, [a], [b])</insert><dialog title="Insert SequenceMatcher">SequenceMatcher(%0, %1, %2)</dialog><info title="Info window"></info></function>

6072

6073

6074

<description>Set the two sequences to be compared.</description>

6075

6076

6077

6078

6079

<description>Set the first sequence to be compared. The second sequence to be

6080

compared is not changed.</description>

6081

6082

6083

6084

6085

<description>Set the second sequence to be compared. The first sequence to be

6086

compared is not changed.</description>

6087

6088

6089

6090

6091

<description>Find longest matching block in a[alo:ahi]

6092

and b[blo:bhi].

6093

If isjunk was omitted or None,

6094

get_longest_match() returns (i, j,

6095

k) such that a[i:i+k] is equal

6096

to b[j:j+k], where

6097

alo <= i <= i+k <= ahi and

6098

blo <= j <= j+k <= bhi.

6099

For all (i', j', k') meeting those

6100

conditions, the additional conditions

6101

k >= k',

6102

i <= i',

6103

and if i == i', j <= j'

6104

are also met.

6105

In other words, of all maximal matching blocks, return one that

6106

starts earliest in a, and of all those maximal matching blocks

6107

that start earliest in a, return the one that starts earliest

6108

in b.

6109

>>> s = SequenceMatcher(None, " abcd", "abcd abcd")

6110

>>> s.find_longest_match(0, 5, 0, 9)

6111

(0, 4, 5)

6112

If isjunk was provided, first the longest matching block is

6113

determined as above, but with the additional restriction that no

6114

junk element appears in the block. Then that block is extended as

6115

far as possible by matching (only) junk elements on both sides.

6116

So the resulting block never matches on junk except as identical

6117

junk happens to be adjacent to an interesting match.

6118

Here's the same example as before, but considering blanks to be junk.

6119

That prevents ' abcd' from matching the ' abcd' at the

6120

tail end of the second sequence directly. Instead only the

6121

'abcd' can match, and matches the leftmost 'abcd' in

6122

the second sequence:

6123

>>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")

6124

>>> s.find_longest_match(0, 5, 0, 9)

6125

(1, 0, 4)

6126

If no blocks match, this returns (alo, blo, 0).</description>

6127

6128

<insert>find_longest_match(alo, ahi, blo, bhi bhi)</insert><dialog title="Insert find_longest_match">find_longest_match(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

6129

6130

6131

<description>Return list of triples describing matching subsequences.

6132

Each triple is of the form (i, j, n), and

6133

means that a[i:i+n] ==

6134

b[j:j+n]. The triples are monotonically

6135

increasing in i and j.

6136

The last triple is a dummy, and has the value (len(a),

6137

len(b), 0). It is the only triple with n == 0.

6138

% Explain why a dummy is used!

6139

>>> s = SequenceMatcher(None, "abxcd", "abcd")

6140

>>> s.get_matching_blocks()

6141

[(0, 0, 2), (3, 2, 2), (5, 4, 0)]

6142

</description>

6143

6144

<insert>get_matching_blocks()</insert><dialog title="Insert get_matching_blocks">get_matching_blocks()</dialog><info title="Info window"></info></function>

6145

6146

6147

<description>Return list of 5-tuples describing how to turn a into b.

6148

Each tuple is of the form (tag, i1, i2,

6149

j1, j2). The first tuple has i1 ==

6150

j1 == 0, and remaining tuples have i1 equal to the

6151

i2 from the preceeding tuple, and, likewise, j1 equal to

6152

the previous j2.

6153

The tag values are strings, with these meanings:

6154

{l|l}{code}{Value}{Meaning}

6155

'replace'{a[i1:i2] should be

6156

replaced by b[j1:j2].}

6157

'delete'{a[i1:i2] should be

6158

deleted. Note that j1 == j2 in

6159

this case.}

6160

'insert'{b[j1:j2] should be

6161

inserted at a[i1:i1].

6162

Note that i1 == i2 in this

6163

case.}

6164

'equal'{a[i1:i2] ==

6165

b[j1:j2] (the sub-sequences are

6166

equal).}

6167

For example:

6168

>>> a = "qabxcd"

6169

>>> b = "abycdf"

6170

>>> s = SequenceMatcher(None, a, b)

6171

>>> for tag, i1, i2, j1, j2 in s.get_opcodes():

6172

... print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %

6173

... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2]))

6174

delete a[0:1] (q) b[0:0] ()

6175

equal a[1:3] (ab) b[0:2] (ab)

6176

replace a[3:4] (x) b[2:3] (y)

6177

equal a[4:6] (cd) b[3:5] (cd)

6178

insert a[6:6] () b[5:6] (f)

6179

</description>

6180

6181

<insert>get_opcodes()</insert><dialog title="Insert get_opcodes">get_opcodes()</dialog><info title="Info window"></info></function>

6182

6183

6184

<description>Return a generator of groups with up to n lines of context.

6185

Starting with the groups returned by get_opcodes(),

6186

this method splits out smaller change clusters and eliminates

6187

intervening ranges which have no changes.

6188

The groups are returned in the same format as get_opcodes().

6189

New in version 2.3</description>

6190

6191

<insert>get_grouped_opcodes(n)</insert><dialog title="Insert get_grouped_opcodes">get_grouped_opcodes(%0)</dialog><info title="Info window"></info></function>

6192

6193

6194

<description>Return a measure of the sequences' similarity as a float in the

6195

range [0, 1].

6196

Where T is the total number of elements in both sequences, and M is

6197

the number of matches, this is 2.0*M / T. Note that this is

6198

1.0 if the sequences are identical, and 0.0 if they

6199

have nothing in common.

6200

This is expensive to compute if get_matching_blocks() or

6201

get_opcodes() hasn't already been called, in which case you

6202

may want to try quick_ratio() or

6203

real_quick_ratio() first to get an upper bound.</description>

6204

6205

<insert>ratio()</insert><dialog title="Insert ratio">ratio()</dialog><info title="Info window"></info></function>

6206

6207

6208

<description>Return an upper bound on ratio() relatively quickly.

6209

This isn't defined beyond that it is an upper bound on

6210

ratio(), and is faster to compute.</description>

6211

6212

<insert>quick_ratio()</insert><dialog title="Insert quick_ratio">quick_ratio()</dialog><info title="Info window"></info></function>

6213

6214

6215

<description>Return an upper bound on ratio() very quickly.

6216

This isn't defined beyond that it is an upper bound on

6217

ratio(), and is faster to compute than either

6218

ratio() or quick_ratio().</description>

6219

6220

<insert>real_quick_ratio()</insert><dialog title="Insert real_quick_ratio">real_quick_ratio()</dialog><info title="Info window"></info></function>

6221

6222

</group>

6223

6224

<description>This example compares two strings, considering blanks to be ``junk:''

6225

>>> s = SequenceMatcher(lambda x: x == " ",

6226

... "private Thread currentThread;",

6227

... "private volatile Thread currentThread;")

6228

ratio() returns a float in [0, 1], measuring the similarity

6229

of the sequences. As a rule of thumb, a ratio() value over

6230

0.6 means the sequences are close matches:

6231

>>> print round(s.ratio(), 3)

6232

0.866

6233

If you're only interested in where the sequences match,

6234

get_matching_blocks() is handy:

6235

>>> for block in s.get_matching_blocks():

6236

... print "a[%d] and b[%d] match for %d elements" % block

6237

a[0] and b[0] match for 8 elements

6238

a[8] and b[17] match for 6 elements

6239

a[14] and b[23] match for 15 elements

6240

a[29] and b[38] match for 0 elements

6241

Note that the last tuple returned by get_matching_blocks() is

6242

always a dummy, (len(a), len(b), 0), and this is

6243

the only case in which the last tuple element (number of elements

6244

matched) is 0.

6245

If you want to know how to change the first sequence into the second,

6246

use get_opcodes():

6247

>>> for opcode in s.get_opcodes():

6248

... print "%6s a[%d:%d] b[%d:%d]" % opcode

6249

equal a[0:8] b[0:8]

6250

insert a[8:8] b[8:17]

6251

equal a[8:14] b[17:23]

6252

equal a[14:29] b[23:38]

6253

See also the function get_close_matches() in this module,

6254

which shows how simple code building on SequenceMatcher can be

6255

used to do useful work.

6256

</description>

6257

</group>

6258

6259

<description>Note that Differ-generated deltas make no claim to be

6260

minimal diffs. To the contrary, minimal diffs are often

6261

counter-intuitive, because they synch up anywhere possible, sometimes

6262

accidental matches 100 pages apart. Restricting synch points to

6263

contiguous matches preserves some notion of locality, at the

6264

occasional cost of producing a longer diff.

6265

The Differ class has this constructor:

6266

</description>

6267

6268

<description>Optional keyword parameters linejunk and charjunk are

6269

for filter functions (or None):

6270

linejunk: A function that accepts a single string

6271

argument, and returns true if the string is junk. The default is

6272

None, meaning that no line is considered junk.

6273

charjunk: A function that accepts a single character argument

6274

(a string of length 1), and returns true if the character is junk.

6275

The default is None, meaning that no character is

6276

considered junk.</description>

6277

<param name="linejunk" optional="0">linejunk</param><param name="charjunk" optional="1">charjunk</param>

6278

<insert>Differ(linejunk, [charjunk])</insert><dialog title="Insert Differ">Differ(%0, %1)</dialog><info title="Info window"></info></function>

6279

6280

6281

<description>Compare two sequences of lines, and generate the delta (a sequence

6282

of lines).

6283

Each sequence must contain individual single-line strings ending

6284

with newlines. Such sequences can be obtained from the

6285

readlines() method of file-like objects. The delta generated

6286

also consists of newline-terminated strings, ready to be printed as-is

6287

via the writelines() method of a file-like object.</description>

6288

6289

<insert>compare(a, b b)</insert><dialog title="Insert compare">compare(%0, %1)</dialog><info title="Info window"></info></function>

6290

6291

</group>

6292

6293

</group>

6294

</group>

6295

6296

<description>General floating point formatting functions.

6297

The fpformat module defines functions for dealing with

6298

floating point numbers representations in 100% pure

6299

Python. This module is unneeded: everything here could

6300

be done via the % string interpolation operator.

6301

The fpformat module defines the following functions and an

6302

exception:

6303

</description>

6304

6305

<description>Format x as [-]ddd.ddd with digs digits after the

6306

point and at least one digit before.

6307

If digs <= 0, the decimal point is suppressed.

6308

x can be either a number or a string that looks like

6309

one. digs is an integer.

6310

Return value is a string.</description>

6311

6312

6313

6314

6315

<description>Format x as [-]d.dddE[+-]ddd with digs digits after the point and exactly one digit before.

6316

If digs <= 0, one digit is kept and the point is suppressed.

6317

x can be either a real number, or a string that looks like

6318

one. digs is an integer.

6319

Return value is a string.</description>

6320

6321

6322

6323

</group>

6324

6325

<description>Read and write strings as if they were files.

6326

This module implements a file-like class, StringIO,

6327

that reads and writes a string buffer (also known as memory

6328

files). See the description of file objects for operations (section

6329

bltin-file-objects).

6330

</description>

6331

6332

<description>When a StringIO object is created, it can be initialized

6333

to an existing string by passing the string to the constructor.

6334

If no string is given, the StringIO will start empty.

6335

The StringIO object can accept either Unicode or 8-bit

6336

strings, but mixing the two may take some care. If both are used,

6337

8-bit strings that cannot be interpreted as 7-bit ASCII (that

6338

use the 8th bit) will cause a UnicodeError to be raised

6339

when getvalue() is called.</description>

6340

<param name="buffer" optional="0">buffer</param>

6341

<insert>StringIO(buffer)</insert><dialog title="Insert StringIO">StringIO(%0)</dialog><info title="Info window"></info></function>

6342

6343

6344

<description>Retrieve the entire contents of the ``file'' at any time before the

6345

StringIO object's close() method is called. See the

6346

note above for information about mixing Unicode and 8-bit strings;

6347

such mixing can cause this method to raise UnicodeError.</description>

6348

6349

<insert>getvalue()</insert><dialog title="Insert getvalue">getvalue()</dialog><info title="Info window"></info></function>

6350

6351

6352

<description>Free the memory buffer.</description>

6353

6354

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

6355

6356

</group>

6357

6358

<description>Text wrapping and filling

6359

New in version 2.3

6360

The textwrap module provides two convenience functions,

6361

wrap() and fill(), as well as

6362

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.

6363

</description>

6364

6365

<description>Wraps the single paragraph in text (a string) so every line is at

6366

most width characters long. Returns a list of output lines,

6367

without final newlines.

6368

Optional keyword arguments correspond to the instance attributes of

6369

TextWrapper, documented below. width defaults to

6370

70.</description>

6371

<param name="text" optional="0">text</param><param name="width" optional="1">width</param><param name="moreargs" optional="1">moreargs</param>

6372

<insert>wrap(text, [width], [moreargs])</insert><dialog title="Insert wrap">wrap(%0, %1, %2)</dialog><info title="Info window"></info></function>

6373

6374

6375

<description>Wraps the single paragraph in text, and returns a single string

6376

containing the wrapped paragraph. fill() is shorthand for

6377

"".join(wrap(text, ...))

6378

In particular, fill() accepts exactly the same keyword

6379

arguments as wrap().</description>

6380

<param name="text" optional="0">text</param><param name="width" optional="1">width</param><param name="moreargs" optional="1">moreargs</param>

6381

<insert>fill(text, [width], [moreargs])</insert><dialog title="Insert fill">fill(%0, %1, %2)</dialog><info title="Info window"></info></function>

6382

6383

6384

<description>Remove any whitespace than can be uniformly removed from the left

6385

of every line in text.

6386

This is typically used to make triple-quoted strings line up with

6387

the left edge of screen/whatever, while still presenting it in the

6388

source code in indented form. For example:

6389

def test():

6390

# end first line with avoid the empty line!

6391

s = '''

6392

world

6393

'''

6394

print repr(s) # prints ' hello world '

6395

print repr(dedent(s)) # prints 'hello world'

6396

</description>

6397

<param name="texttext" optional="0">texttext</param>

6398

<insert>dedent(texttext)</insert><dialog title="Insert dedent">dedent(%0)</dialog><info title="Info window"></info></function>

6399

6400

6401

<description>The TextWrapper constructor accepts a number of optional

6402

keyword arguments. Each argument corresponds to one instance attribute,

6403

so for example

6404

wrapper = TextWrapper(initial_indent="* ")

6405

is the same as

6406

wrapper = TextWrapper()

6407

wrapper.initial_indent = "* "

6408

You can re-use the same TextWrapper object many times, and you

6409

can change any of its options through direct assignment to instance

6410

attributes between uses.</description>

6411

6412

<insert>TextWrapper(......)</insert><dialog title="Insert TextWrapper">TextWrapper(%0)</dialog><info title="Info window"></info></function>

6413

6414

6415

<description>Wraps the single paragraph in text (a string) so every line is

6416

at most width characters long. All wrapping options are

6417

taken from instance attributes of the TextWrapper instance.

6418

Returns a list of output lines, without final newlines.</description>

6419

<param name="texttext" optional="0">texttext</param>

6420

<insert>wrap(texttext)</insert><dialog title="Insert wrap">wrap(%0)</dialog><info title="Info window"></info></function>

6421

6422

6423

<description>Wraps the single paragraph in text, and returns a single string

6424

containing the wrapped paragraph.</description>

6425

<param name="texttext" optional="0">texttext</param>

6426

<insert>fill(texttext)</insert><dialog title="Insert fill">fill(%0)</dialog><info title="Info window"></info></function>

6427

6428

</group>

6429

6430

<description>Encode and decode data and streams.

6431

</description>

6432

6433

<description>Register a codec search function. Search functions are expected to

6434

take one argument, the encoding name in all lower case letters, and

6435

return a tuple of functions (encoder, decoder, stream_reader,

6436

stream_writer) taking the following arguments:

6437

encoder and decoder: These must be functions or methods

6438

which have the same interface as the

6439

encode()/decode() methods of Codec instances (see

6440

Codec Interface). The functions/methods are expected to work in a

6441

stateless mode.

6442

stream_reader and stream_writer: These have to be

6443

factory functions providing the following interface:

6444

factory(stream, errors='strict')

6445

The factory functions must return objects providing the interfaces

6446

defined by the base classes StreamWriter and

6447

StreamReader, respectively. Stream codecs can maintain

6448

state.

6449

Possible values for errors are 'strict' (raise an exception

6450

in case of an encoding error), 'replace' (replace malformed

6451

data with a suitable replacement marker, such as ?),

6452

'ignore' (ignore malformed data and continue without further

6453

notice), 'xmlcharrefreplace' (replace with the appropriate XML

6454

character reference (for encoding only)) and 'backslashreplace'

6455

(replace with backslashed escape sequences (for encoding only)) as

6456

well as any other error handling name defined via

6457

register_error().

6458

In case a search function cannot find a given encoding, it should

6459

return None.</description>

6460

<param name="search_functionsearch_function" optional="0">search_functionsearch_function</param>

6461

<insert>register(search_functionsearch_function)</insert><dialog title="Insert register">register(%0)</dialog><info title="Info window"></info></function>

6462

6463

6464

<description>Looks up a codec tuple in the Python codec registry and returns the

6465

function tuple as defined above.

6466

Encodings are first looked up in the registry's cache. If not found,

6467

the list of registered search functions is scanned. If no codecs tuple

6468

is found, a LookupError is raised. Otherwise, the codecs

6469

tuple is stored in the cache and returned to the caller.</description>

6470

<param name="encodingencoding" optional="0">encodingencoding</param>

6471

<insert>lookup(encodingencoding)</insert><dialog title="Insert lookup">lookup(%0)</dialog><info title="Info window"></info></function>

6472

6473

6474

<description>Lookup up the codec for the given encoding and return its encoder

6475

function.

6476

Raises a LookupError in case the encoding cannot be found.</description>

6477

<param name="encodingencoding" optional="0">encodingencoding</param>

6478

<insert>getencoder(encodingencoding)</insert><dialog title="Insert getencoder">getencoder(%0)</dialog><info title="Info window"></info></function>

6479

6480

6481

<description>Lookup up the codec for the given encoding and return its decoder

6482

function.

6483

Raises a LookupError in case the encoding cannot be found.</description>

6484

<param name="encodingencoding" optional="0">encodingencoding</param>

6485

<insert>getdecoder(encodingencoding)</insert><dialog title="Insert getdecoder">getdecoder(%0)</dialog><info title="Info window"></info></function>

6486

6487

6488

<description>Lookup up the codec for the given encoding and return its StreamReader

6489

class or factory function.

6490

Raises a LookupError in case the encoding cannot be found.</description>

6491

<param name="encodingencoding" optional="0">encodingencoding</param>

6492

<insert>getreader(encodingencoding)</insert><dialog title="Insert getreader">getreader(%0)</dialog><info title="Info window"></info></function>

6493

6494

6495

<description>Lookup up the codec for the given encoding and return its StreamWriter

6496

class or factory function.

6497

Raises a LookupError in case the encoding cannot be found.</description>

6498

<param name="encodingencoding" optional="0">encodingencoding</param>

6499

<insert>getwriter(encodingencoding)</insert><dialog title="Insert getwriter">getwriter(%0)</dialog><info title="Info window"></info></function>

6500

6501

6502

<description>Register the error handling function error_handler under the

6503

name name. error_handler will be called during encoding

6504

and decoding in case of an error, when name is specified as the

6505

errors parameter.

6506

For encoding error_handler will be called with a

6507

UnicodeEncodeError instance, which contains information about

6508

the location of the error. The error handler must either raise this or

6509

a different exception or return a tuple with a replacement for the

6510

unencodable part of the input and a position where encoding should

6511

continue. The encoder will encode the replacement and continue encoding

6512

the original input at the specified position. Negative position values

6513

will be treated as being relative to the end of the input string. If the

6514

resulting position is out of bound an IndexError will be raised.

6515

Decoding and translating works similar, except UnicodeDecodeError

6516

or UnicodeTranslateError will be passed to the handler and

6517

that the replacement from the error handler will be put into the output

6518

directly.</description>

6519

<param name="name" optional="0">name</param><param name="error_handler error_handler" optional="0">error_handler error_handler</param>

6520

<insert>register_error(name, error_handler error_handler)</insert><dialog title="Insert register_error">register_error(%0, %1)</dialog><info title="Info window"></info></function>

6521

6522

6523

<description>Return the error handler previously register under the name name.

6524

Raises a LookupError in case the handler cannot be found.</description>

6525

<param name="namename" optional="0">namename</param>

6526

<insert>lookup_error(namename)</insert><dialog title="Insert lookup_error">lookup_error(%0)</dialog><info title="Info window"></info></function>

6527

6528

6529

<description>Implements the strict error handling.</description>

6530

<param name="exceptionexception" optional="0">exceptionexception</param>

6531

<insert>strict_errors(exceptionexception)</insert><dialog title="Insert strict_errors">strict_errors(%0)</dialog><info title="Info window"></info></function>

6532

6533

6534

<description>Implements the replace error handling.</description>

6535

<param name="exceptionexception" optional="0">exceptionexception</param>

6536

<insert>replace_errors(exceptionexception)</insert><dialog title="Insert replace_errors">replace_errors(%0)</dialog><info title="Info window"></info></function>

6537

6538

6539

<description>Implements the ignore error handling.</description>

6540

<param name="exceptionexception" optional="0">exceptionexception</param>

6541

<insert>ignore_errors(exceptionexception)</insert><dialog title="Insert ignore_errors">ignore_errors(%0)</dialog><info title="Info window"></info></function>

6542

6543

6544

<description>Implements the xmlcharrefreplace error handling.</description>

6545

<param name="exceptionexception" optional="0">exceptionexception</param>

6546

<insert>xmlcharrefreplace_errors_errors(exceptionexception)</insert><dialog title="Insert xmlcharrefreplace_errors_errors">xmlcharrefreplace_errors_errors(%0)</dialog><info title="Info window"></info></function>

6547

6548

6549

<description>Implements the backslashreplace error handling.</description>

6550

<param name="exceptionexception" optional="0">exceptionexception</param>

6551

<insert>backslashreplace_errors_errors(exceptionexception)</insert><dialog title="Insert backslashreplace_errors_errors">backslashreplace_errors_errors(%0)</dialog><info title="Info window"></info></function>

6552

6553

6554

<description>Open an encoded file using the given mode and return

6555

a wrapped version providing transparent encoding/decoding.

6556

The wrapped version will only accept the object format

6557

defined by the codecs, i.e. objects for most built-in

6558

codecs. Output is also codec-dependent and will usually be Unicode as

6559

well.

6560

encoding specifies the encoding which is to be used for the

6561

file.

6562

errors may be given to define the error handling. It defaults

6563

to 'strict' which causes a ValueError to be raised

6564

in case an encoding error occurs.

6565

buffering has the same meaning as for the built-in

6566

open() function. It defaults to line buffered.</description>

6567

<param name="filename" optional="0">filename</param><param name="mode" optional="0">mode</param><param name="encoding" optional="1">encoding</param><param name="errors" optional="1">errors</param><param name="buffering" optional="1">buffering</param>

6568

<insert>open(filename, mode, [encoding], [errors], [buffering])</insert><dialog title="Insert open">open(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

6569

6570

6571

<description>Return a wrapped version of file which provides transparent

6572

encoding translation.

6573

Strings written to the wrapped file are interpreted according to the

6574

given input encoding and then written to the original file as

6575

strings using the output encoding. The intermediate encoding will

6576

usually be Unicode but depends on the specified codecs.

6577

If output is not given, it defaults to input.

6578

errors may be given to define the error handling. It defaults to

6579

'strict', which causes ValueError to be raised in case

6580

an encoding error occurs.</description>

6581

<param name="file" optional="0">file</param><param name="input" optional="0">input</param><param name="output" optional="1">output</param><param name="errors" optional="1">errors</param>

6582

<insert>EncodedFile(file, input, [output], [errors])</insert><dialog title="Insert EncodedFile">EncodedFile(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

6583

6584

6585

<description>The codecs defines a set of base classes which define the

6586

interface and can also be used to easily write you own codecs for use

6587

in Python.

6588

Each codec has to define four interfaces to make it usable as codec in

6589

Python: stateless encoder, stateless decoder, stream reader and stream

6590

writer. The stream reader and writers typically reuse the stateless

6591

encoder/decoder to implement the file protocols.

6592

The Codec class defines the interface for stateless

6593

encoders/decoders.

6594

To simplify and standardize error handling, the encode() and

6595

decode() methods may implement different error handling

6596

schemes by providing the errors string argument. The following

6597

string values are defined and implemented by all standard Python

6598

codecs:

6599

{l|l}{code}{Value}{Meaning}

6600

'strict'{Raise UnicodeError (or a subclass);

6601

this is the default.}

6602

'ignore'{Ignore the character and continue with the next.}

6603

'replace'{Replace with a suitable replacement character;

6604

Python will use the official U+FFFD REPLACEMENT

6605

CHARACTER for the built-in Unicode codecs on

6606

decoding and '?' on encoding.}

6607

'xmlcharrefreplace'{Replace with the appropriate XML

6608

character reference (only for encoding).}

6609

'backslashreplace'{Replace with backslashed escape sequences

6610

(only for encoding).}

6611

The set of allowed values can be extended via register_error.

6612

Codec Objects The Codec class defines these methods which also define the

6613

function interfaces of the stateless encoder and decoder:

6614

</description>

6615

6616

<description>Encodes the object input and returns a tuple (output object,

6617

length consumed). While codecs are not restricted to use with Unicode, in

6618

a Unicode context, encoding converts a Unicode object to a plain string

6619

using a particular character set encoding (e.g., cp1252 or

6620

iso-8859-1).

6621

errors defines the error handling to apply. It defaults to

6622

'strict' handling.

6623

The method may not store state in the Codec instance. Use

6624

StreamCodec for codecs which have to keep state in order to

6625

make encoding/decoding efficient.

6626

The encoder must be able to handle zero length input and return an

6627

empty object of the output object type in this situation.</description>

6628

<param name="input" optional="0">input</param><param name="errors" optional="1">errors</param>

6629

<insert>encode(input, [errors])</insert><dialog title="Insert encode">encode(%0, %1)</dialog><info title="Info window"></info></function>

6630

6631

6632

<description>Decodes the object input and returns a tuple (output object,

6633

length consumed). In a Unicode context, decoding converts a plain string

6634

encoded using a particular character set encoding to a Unicode object.

6635

input must be an object which provides the bf_getreadbuf

6636

buffer slot. Python strings, buffer objects and memory mapped files

6637

are examples of objects providing this slot.

6638

errors defines the error handling to apply. It defaults to

6639

'strict' handling.

6640

The method may not store state in the Codec instance. Use

6641

StreamCodec for codecs which have to keep state in order to

6642

make encoding/decoding efficient.

6643

The decoder must be able to handle zero length input and return an

6644

empty object of the output object type in this situation.</description>

6645

<param name="input" optional="0">input</param><param name="errors" optional="1">errors</param>

6646

<insert>decode(input, [errors])</insert><dialog title="Insert decode">decode(%0, %1)</dialog><info title="Info window"></info></function>

6647

6648

6649

<description>Constructor for a StreamWriter instance. All stream writers must provide this constructor interface. They are

6650

free to add additional keyword arguments, but only the ones defined

6651

here are used by the Python codec registry.

6652

stream must be a file-like object open for writing (binary)

6653

data.

6654

The StreamWriter may implement different error handling

6655

schemes by providing the errors keyword argument. These

6656

parameters are predefined:

6657

'strict' Raise ValueError (or a subclass);

6658

this is the default.

6659

'ignore' Ignore the character and continue with the next.

6660

'replace' Replace with a suitable replacement character

6661

'xmlcharrefreplace' Replace with the appropriate XML

6662

character reference

6663

'backslashreplace' Replace with backslashed escape sequences.

6664

The errors argument will be assigned to an attribute of the

6665

same name. Assigning to this attribute makes it possible to switch

6666

between different error handling strategies during the lifetime

6667

of the StreamWriter object.

6668

The set of allowed values for the errors argument can

6669

be extended with register_error().</description>

6670

<param name="stream" optional="0">stream</param><param name="errors" optional="1">errors</param>

6671

<insert>StreamWriter(stream, [errors])</insert><dialog title="Insert StreamWriter">StreamWriter(%0, %1)</dialog><info title="Info window"></info></function>

6672

6673

6674

<description>Writes the object's contents encoded to the stream.</description>

6675

<param name="objectobject" optional="0">objectobject</param>

6676

<insert>write(objectobject)</insert><dialog title="Insert write">write(%0)</dialog><info title="Info window"></info></function>

6677

6678

6679

<description>Writes the concatenated list of strings to the stream (possibly by

6680

reusing the write() method).</description>

6681

<param name="listlist" optional="0">listlist</param>

6682

<insert>writelines(listlist)</insert><dialog title="Insert writelines">writelines(%0)</dialog><info title="Info window"></info></function>

6683

6684

6685

<description>Flushes and resets the codec buffers used for keeping state.

6686

Calling this method should ensure that the data on the output is put

6687

into a clean state, that allows appending of new fresh data without

6688

having to rescan the whole stream to recover state.</description>

6689

6690

<insert>reset()</insert><dialog title="Insert reset">reset()</dialog><info title="Info window"></info></function>

6691

6692

6693

<description>Constructor for a StreamReader instance. All stream readers must provide this constructor interface. They are

6694

free to add additional keyword arguments, but only the ones defined

6695

here are used by the Python codec registry.

6696

stream must be a file-like object open for reading (binary)

6697

data.

6698

The StreamReader may implement different error handling

6699

schemes by providing the errors keyword argument. These

6700

parameters are defined:

6701

'strict' Raise ValueError (or a subclass);

6702

this is the default.

6703

'ignore' Ignore the character and continue with the next.

6704

'replace' Replace with a suitable replacement character.

6705

The errors argument will be assigned to an attribute of the

6706

same name. Assigning to this attribute makes it possible to switch

6707

between different error handling strategies during the lifetime

6708

of the StreamReader object.

6709

The set of allowed values for the errors argument can

6710

be extended with register_error().</description>

6711

<param name="stream" optional="0">stream</param><param name="errors" optional="1">errors</param>

6712

<insert>StreamReader(stream, [errors])</insert><dialog title="Insert StreamReader">StreamReader(%0, %1)</dialog><info title="Info window"></info></function>

6713

6714

6715

<description>Decodes data from the stream and returns the resulting object.

6716

size indicates the approximate maximum number of bytes to read

6717

from the stream for decoding purposes. The decoder can modify this

6718

setting as appropriate. The default value -1 indicates to read and

6719

decode as much as possible. size is intended to prevent having

6720

to decode huge files in one step.

6721

The method should use a greedy read strategy meaning that it should

6722

read as much data as is allowed within the definition of the encoding

6723

and the given size, e.g. if optional encoding endings or state

6724

markers are available on the stream, these should be read too.</description>

6725

6726

6727

6728

6729

<description>Read one line from the input stream and return the

6730

decoded data.

6731

Unlike the readlines() method, this method inherits

6732

the line breaking knowledge from the underlying stream's

6733

readline() method -- there is currently no support for line

6734

breaking using the codec decoder due to lack of line buffering.

6735

Sublcasses should however, if possible, try to implement this method

6736

using their own knowledge of line breaking.

6737

size, if given, is passed as size argument to the stream's

6738

readline() method.</description>

6739

6740

<insert>readline([size][size])</insert><dialog title="Insert readline">readline(%0)</dialog><info title="Info window"></info></function>

6741

6742

6743

<description>Read all lines available on the input stream and return them as list

6744

of lines.

6745

Line breaks are implemented using the codec's decoder method and are

6746

included in the list entries.

6747

sizehint, if given, is passed as size argument to the

6748

stream's read() method.</description>

6749

<param name="[sizehint][sizehint]" optional="0">[sizehint][sizehint]</param>

6750

<insert>readlines([sizehint][sizehint])</insert><dialog title="Insert readlines">readlines(%0)</dialog><info title="Info window"></info></function>

6751

6752

6753

<description>Resets the codec buffers used for keeping state.

6754

Note that no stream repositioning should take place. This method is

6755

primarily intended to be able to recover from decoding errors.</description>

6756

6757

<insert>reset()</insert><dialog title="Insert reset">reset()</dialog><info title="Info window"></info></function>

6758

6759

6760

<description>Creates a StreamReaderWriter instance.

6761

stream must be a file-like object.

6762

Reader and Writer must be factory functions or classes

6763

providing the StreamReader and StreamWriter interface

6764

resp.

6765

Error handling is done in the same way as defined for the

6766

stream readers and writers.</description>

6767

<param name="stream" optional="0">stream</param><param name="Reader" optional="0">Reader</param><param name="Writer" optional="0">Writer</param><param name="errors errors" optional="0">errors errors</param>

6768

<insert>StreamReaderWriter(stream, Reader, Writer, errors errors)</insert><dialog title="Insert StreamReaderWriter">StreamReaderWriter(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

6769

6770

6771

<description>Creates a StreamRecoder instance which implements a two-way

6772

conversion: encode and decode work on the frontend (the

6773

input to read() and output of write()) while

6774

Reader and Writer work on the backend (reading and

6775

writing to the stream).

6776

You can use these objects to do transparent direct recodings from

6777

e.g.-1 to UTF-8 and back.

6778

stream must be a file-like object.

6779

encode, decode must adhere to the Codec

6780

interface, Reader, Writer must be factory functions or

6781

classes providing objects of the StreamReader and

6782

StreamWriter interface respectively.

6783

encode and decode are needed for the frontend

6784

translation, Reader and Writer for the backend

6785

translation. The intermediate format used is determined by the two

6786

sets of codecs, e.g. the Unicode codecs will use Unicode as

6787

intermediate encoding.

6788

Error handling is done in the same way as defined for the

6789

stream readers and writers.</description>

6790

<param name="stream" optional="0">stream</param><param name="encode" optional="0">encode</param><param name="decode" optional="0">decode</param><param name="Reader" optional="0">Reader</param><param name="Writer" optional="0">Writer</param><param name="errors errors" optional="0">errors errors</param>

6791

<insert>StreamRecoder(stream, encode, decode, Reader, Writer, errors errors)</insert><dialog title="Insert StreamRecoder">StreamRecoder(%0, %1, %2, %3, %4, %5)</dialog><info title="Info window"></info></function>

6792

6793

</group>

6794

6795

<description>Python comes with a number of codecs builtin, either implemented as C

6796

functions, or with dictionaries as mapping tables. The following table

6797

lists the codecs by name, together with a few common aliases, and the

6798

languages for which the encoding is likely used. Neither the list of

6799

aliases nor the list of languages is meant to be exhaustive. Notice

6800

that spelling alternatives that only differ in case or use a hyphen

6801

instead of an underscore are also valid aliases.

6802

Many of the character sets support the same languages. They vary in

6803

individual characters (e.g. whether the EURO SIGN is supported or

6804

not), and in the assignment of characters to code positions. For the

6805

European languages in particular, the following variants typically

6806

exist:

6807

an ISO 8859 codeset

6808

a Microsoft Windows code page, which is typically derived from

6809

a 8859 codeset, but replaces control characters with additional

6810

graphic characters

6811

an IBM EBCDIC code page

6812

an IBM PC code page, which is ASCII compatible

6813

{l|l|l}{textrm}{Codec}{Aliases}{Languages}

6814

ascii

6815

{646, us-ascii}

6816

{English}

6817

cp037

6818

{IBM037, IBM039}

6819

{English}

6820

cp424

6821

{EBCDIC-CP-HE, IBM424}

6822

{Hebrew}

6823

cp437

6824

{437, IBM437}

6825

{English}

6826

cp500

6827

{EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500}

6828

{Western Europe}

6829

cp737

6830

{}

6831

{Greek}

6832

cp775

6833

{IBM775}

6834

{Baltic languages}

6835

cp850

6836

{850, IBM850}

6837

{Western Europe}

6838

cp852

6839

{852, IBM852}

6840

{Central and Eastern Europe}

6841

cp855

6842

{855, IBM855}

6843

{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}

6844

cp856

6845

{}

6846

{Hebrew}

6847

cp857

6848

{857, IBM857}

6849

{Turkish}

6850

cp860

6851

{860, IBM860}

6852

{Portuguese}

6853

cp861

6854

{861, CP-IS, IBM861}

6855

{Icelandic}

6856

cp862

6857

{862, IBM862}

6858

{Hebrew}

6859

cp863

6860

{863, IBM863}

6861

{Canadian}

6862

cp864

6863

{IBM864}

6864

{Arabic}

6865

cp865

6866

{865, IBM865}

6867

{Danish, Norwegian}

6868

cp869

6869

{869, CP-GR, IBM869}

6870

{Greek}

6871

cp874

6872

{}

6873

{Thai}

6874

cp875

6875

{}

6876

{Greek}

6877

cp1006

6878

{}

6879

{Urdu}

6880

cp1026

6881

{ibm1026}

6882

{Turkish}

6883

cp1140

6884

{ibm1140}

6885

{Western Europe}

6886

cp1250

6887

{windows-1250}

6888

{Central and Eastern Europe}

6889

cp1251

6890

{windows-1251}

6891

{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}

6892

cp1252

6893

{windows-1252}

6894

{Western Europe}

6895

cp1253

6896

{windows-1253}

6897

{Greek}

6898

cp1254

6899

{windows-1254}

6900

{Turkish}

6901

cp1255

6902

{windows-1255}

6903

{Hebrew}

6904

cp1256

6905

{windows1256}

6906

{Arabic}

6907

cp1257

6908

{windows-1257}

6909

{Baltic languages}

6910

cp1258

6911

{windows-1258}

6912

{Vietnamese}

6913

latin_1

6914

{iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1}

6915

{West Europe}

6916

iso8859_2

6917

{iso-8859-2, latin2, L2}

6918

{Central and Eastern Europe}

6919

iso8859_3

6920

{iso-8859-3, latin3, L3}

6921

{Esperanto, Maltese}

6922

iso8859_4

6923

{iso-8859-4, latin4, L4}

6924

{Baltic languagues}

6925

iso8859_5

6926

{iso-8859-5, cyrillic}

6927

{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}

6928

iso8859_6

6929

{iso-8859-6, arabic}

6930

{Arabic}

6931

iso8859_7

6932

{iso-8859-7, greek, greek8}

6933

{Greek}

6934

iso8859_8

6935

{iso-8859-8, hebrew}

6936

{Hebrew}

6937

iso8859_9

6938

{iso-8859-9, latin5, L5}

6939

{Turkish}

6940

iso8859_10

6941

{iso-8859-10, latin6, L6}

6942

{Nordic languages}

6943

iso8859_13

6944

{iso-8859-13}

6945

{Baltic languages}

6946

iso8859_14

6947

{iso-8859-14, latin8, L8}

6948

{Celtic languages}

6949

iso8859_15

6950

{iso-8859-15}

6951

{Western Europe}

6952

koi8_r

6953

{}

6954

{Russian}

6955

koi8_u

6956

{}

6957

{Ukrainian}

6958

mac_cyrillic

6959

{maccyrillic}

6960

{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}

6961

mac_greek

6962

{macgreek}

6963

{Greek}

6964

mac_iceland

6965

{maciceland}

6966

{Icelandic}

6967

mac_latin2

6968

{maclatin2, maccentraleurope}

6969

{Central and Eastern Europe}

6970

mac_roman

6971

{macroman}

6972

{Western Europe}

6973

mac_turkish

6974

{macturkish}

6975

{Turkish}

6976

utf_16

6977

{U16, utf16}

6978

{all languages}

6979

utf_16_be

6980

{UTF-16BE}

6981

{all languages (BMP only)}

6982

utf_16_le

6983

{UTF-16LE}

6984

{all languages (BMP only)}

6985

utf_7

6986

{U7}

6987

{all languages}

6988

utf_8

6989

{U8, UTF, utf8}

6990

{all languages}

6991

A number of codecs are specific to Python, so their codec names have

6992

no meaning outside Python. Some of them don't convert from Unicode

6993

strings to byte strings, but instead use the property of the Python

6994

codecs machinery that any bijective function with one argument can be

6995

considered as an encoding.

6996

For the codecs listed below, the result in the ``encoding'' direction

6997

is always a byte string. The result of the ``decoding'' direction is

6998

listed as operand type in the table.

6999

{l|l|l|l}{textrm}{Codec}{Aliases}{Operand type}{Purpose}

7000

base64_codec

7001

{base64, base-64}

7002

{byte string}

7003

{Convert operand to MIME base64}

7004

bz2_codec

7005

{bz2}

7006

{byte string}

7007

{Compress the operand using bz2}

7008

hex_codec

7009

{hex}

7010

{byte string}

7011

{Convert operand to hexadecimal representation, with two

7012

digits per byte}

7013

idna

7014

{}

7015

{Unicode string}

7016

{Implements 3490.

7017

New in version 2.3

7018

See also Curses

13675

Programming with Python - Tutorial material on using curses

13676

with Python, by Andrew Kuchling and Eric Raymond, is

13677

available on the Python Web site.

13678

The Demo/curses/ directory in the Python source

13679

distribution contains some example programs using the

13680

curses bindings provided by this module.

13681

</description>

13682

13683

<description>The module curses defines the following exception:

13684

{error}

13685

Exception raised when a curses library function returns an error.

13686

Whenever x or y arguments to a function

13687

or a method are optional, they default to the current cursor location.

13688

Whenever attr is optional, it defaults to A_NORMAL.

13689

The module curses defines the following functions:

13690

</description>

13691

13692

<description>Returns the output speed of the terminal in bits per second. On

13693

software terminal emulators it will have a fixed high value.

13694

Included for historical reasons; in former times, it was used to write output loops for time delays and occasionally to change

13695

interfaces depending on the line speed.</description>

13696

13697

<insert>baudrate()</insert><dialog title="Insert baudrate">baudrate()</dialog><info title="Info window"></info></function>

13698

13699

13700

<description>Emit a short attention sound.</description>

13701

13702

13703

13704

13705

<description>Returns true or false, depending on whether the programmer can change

13706

the colors displayed by the terminal.</description>

13707

13708

<insert>can_change_color()</insert><dialog title="Insert can_change_color">can_change_color()</dialog><info title="Info window"></info></function>

13709

13710

13711

<description>Enter cbreak mode. In cbreak mode (sometimes called ``rare'' mode)

13712

normal tty line buffering is turned off and characters are available

13713

to be read one by one. However, unlike raw mode, special characters

13714

(interrupt, quit, suspend, and flow control) retain their effects on

13715

the tty driver and calling program. Calling first raw()

13716

then cbreak() leaves the terminal in cbreak mode.</description>

13717

13718

<insert>cbreak()</insert><dialog title="Insert cbreak">cbreak()</dialog><info title="Info window"></info></function>

13719

13720

13721

<description>Returns the intensity of the red, green, and blue (RGB) components in

13722

the color color_number, which must be between 0 and

13723

COLORS. A 3-tuple is returned, containing the R,G,B values

13724

for the given color, which will be between 0 (no component) and

13725

1000 (maximum amount of component).</description>

13726

<param name="color_numbercolor_number" optional="0">color_numbercolor_number</param>

13727

<insert>color_content(color_numbercolor_number)</insert><dialog title="Insert color_content">color_content(%0)</dialog><info title="Info window"></info></function>

13728

13729

13730

<description>Returns the attribute value for displaying text in the specified

13731

color. This attribute value can be combined with

13732

A_STANDOUT, A_REVERSE, and the other

13733

A_* attributes. pair_number() is the

13734

counterpart to this function.</description>

13735

<param name="color_numbercolor_number" optional="0">color_numbercolor_number</param>

13736

<insert>color_pair(color_numbercolor_number)</insert><dialog title="Insert color_pair">color_pair(%0)</dialog><info title="Info window"></info></function>

13737

13738

13739

<description>Sets the cursor state. visibility can be set to 0, 1, or 2, for

13740

invisible, normal, or very visible. If the terminal supports the

13741

visibility requested, the previous cursor state is returned;

13742

otherwise, an exception is raised. On many terminals, the ``visible''

13743

mode is an underline cursor and the ``very visible'' mode is a block cursor.</description>

13744

<param name="visibilityvisibility" optional="0">visibilityvisibility</param>

13745

<insert>curs_set(visibilityvisibility)</insert><dialog title="Insert curs_set">curs_set(%0)</dialog><info title="Info window"></info></function>

13746

13747

13748

<description>Saves the current terminal mode as the ``program'' mode, the mode when

13749

the running program is using curses. (Its counterpart is the

13750

``shell'' mode, for when the program is not in curses.) Subsequent calls

13751

to reset_prog_mode() will restore this mode.</description>

13752

13753

13754

13755

13756

<description>Saves the current terminal mode as the ``shell'' mode, the mode when

13757

the running program is not using curses. (Its counterpart is the

13758

``program'' mode, when the program is using curses capabilities.)

13759

Subsequent calls

13760

to reset_shell_mode() will restore this mode.</description>

13761

13762

<insert>def_shell_mode()</insert><dialog title="Insert def_shell_mode">def_shell_mode()</dialog><info title="Info window"></info></function>

13763

13764

13765

<description>Inserts an ms millisecond pause in output.</description>

13766

13767

<insert>delay_output(msms)</insert><dialog title="Insert delay_output">delay_output(%0)</dialog><info title="Info window"></info></function>

13768

13769

13770

<description>Update the physical screen. The curses library keeps two data

13771

structures, one representing the current physical screen contents

13772

and a virtual screen representing the desired next state. The

13773

doupdate() ground updates the physical screen to match the

13774

virtual screen.

13775

The virtual screen may be updated by a noutrefresh() call

13776

after write operations such as addstr() have been performed

13777

on a window. The normal refresh() call is simply

13778

noutrefresh() followed by doupdate(); if you have

13779

to update multiple windows, you can speed performance and perhaps

13780

reduce screen flicker by issuing noutrefresh() calls on

13781

all windows, followed by a single doupdate().</description>

13782

13783

<insert>doupdate()</insert><dialog title="Insert doupdate">doupdate()</dialog><info title="Info window"></info></function>

13784

13785

13786

<description>Enter echo mode. In echo mode, each character input is echoed to the

13787

screen as it is entered.</description>

13788

13789

13790

13791

13792

<description>De-initialize the library, and return terminal to normal status.</description>

13793

13794

<insert>endwin()</insert><dialog title="Insert endwin">endwin()</dialog><info title="Info window"></info></function>

13795

13796

13797

<description>Returns the user's current erase character. Under operating

13798

systems this is a property of the controlling tty of the curses

13799

program, and is not set by the curses library itself.</description>

13800

13801

<insert>erasechar()</insert><dialog title="Insert erasechar">erasechar()</dialog><info title="Info window"></info></function>

13802

13803

13804

<description>The filter() routine, if used, must be called before

13805

initscr() is called. The effect is that, during those

13806

calls, LINES is set to 1; the capabilities clear, cup, cud, cud1,

13807

cuu1, cuu, vpa are disabled; and the home string is set to the value of cr.

13808

The effect is that the cursor is confined to the current line, and so

13809

are screen updates. This may be used for enabling cgaracter-at-a-time line editing without touching the rest of the screen.</description>

13810

13811

<insert>filter()</insert><dialog title="Insert filter">filter()</dialog><info title="Info window"></info></function>

13812

13813

13814

<description>Flash the screen. That is, change it to reverse-video and then change

13815

it back in a short interval. Some people prefer such as `visible bell'

13816

to the audible attention signal produced by beep().</description>

13817

13818

<insert>flash()</insert><dialog title="Insert flash">flash()</dialog><info title="Info window"></info></function>

13819

13820

13821

<description>Flush all input buffers. This throws away any typeahead that has

13822

been typed by the user and has not yet been processed by the program.</description>

13823

13824

<insert>flushinp()</insert><dialog title="Insert flushinp">flushinp()</dialog><info title="Info window"></info></function>

13825

13826

13827

<description>After getch() returns KEY_MOUSE to signal a mouse

13828

event, this method should be call to retrieve the queued mouse event,

13829

represented as a 5-tuple

13830

(id, x, y, z, bstate).

13831

id is an ID value used to distinguish multiple devices,

13832

and x, y, z are the event's coordinates. (z

13833

is currently unused.). bstate is an integer value whose bits

13834

will be set to indicate the type of event, and will be the bitwise OR

13835

of one or more of the following constants, where n is the button

13836

number from 1 to 4:

13837

BUTTONn_PRESSED,

13838

BUTTONn_RELEASED,

13839

BUTTONn_CLICKED,

13840

BUTTONn_DOUBLE_CLICKED,

13841

BUTTONn_TRIPLE_CLICKED,

13842

BUTTON_SHIFT,

13843

BUTTON_CTRL,

13844

BUTTON_ALT.</description>

13845

13846

<insert>getmouse()</insert><dialog title="Insert getmouse">getmouse()</dialog><info title="Info window"></info></function>

13847

13848

13849

<description>Returns the current coordinates of the virtual screen cursor in y and

13850

x. If leaveok is currently true, then -1,-1 is returned.</description>

13851

13852

<insert>getsyx()</insert><dialog title="Insert getsyx">getsyx()</dialog><info title="Info window"></info></function>

13853

13854

13855

<description>Reads window related data stored in the file by an earlier

13856

putwin() call. The routine then creates and initializes a

13857

new window using that data, returning the new window object.</description>

13858

<param name="filefile" optional="0">filefile</param>

13859

<insert>getwin(filefile)</insert><dialog title="Insert getwin">getwin(%0)</dialog><info title="Info window"></info></function>

13860

13861

13862

<description>Returns true if the terminal can display colors; otherwise, it

13863

returns false.</description>

13864

13865

<insert>has_colors()</insert><dialog title="Insert has_colors">has_colors()</dialog><info title="Info window"></info></function>

13866

13867

13868

<description>Returns true if the terminal has insert- and delete- character

13869

capabilities. This function is included for historical reasons only,

13870

as all modern software terminal emulators have such capabilities.</description>

13871

13872

13873

13874

13875

<description>Returns true if the terminal has insert- and

13876

delete-line capabilities, or can simulate them using

13877

scrolling regions. This function is included for historical reasons only,

13878

as all modern software terminal emulators have such capabilities.</description>

13879

13880

13881

13882

13883

<description>Takes a key value ch, and returns true if the current terminal

13884

type recognizes a key with that value.</description>

13885

13886

13887

13888

13889

<description>Used for half-delay mode, which is similar to cbreak mode in that

13890

characters typed by the user are immediately available to the program.

13891

However, after blocking for tenths tenths of seconds, an

13892

exception is raised if nothing has been typed. The value of

13893

tenths must be a number between 1 and 255. Use

13894

nocbreak() to leave half-delay mode.</description>

13895

<param name="tenthstenths" optional="0">tenthstenths</param>

13896

<insert>halfdelay(tenthstenths)</insert><dialog title="Insert halfdelay">halfdelay(%0)</dialog><info title="Info window"></info></function>

13897

13898

13899

<description>Changes the definition of a color, taking the number of the color to

13900

be changed followed by three RGB values (for the amounts of red,

13901

green, and blue components). The value of color_number must be

13902

between 0 and COLORS. Each of r, g,

13903

b, must be a value between 0 and 1000. When

13904

init_color() is used, all occurrences of that color on the

13905

screen immediately change to the new definition. This function is a

13906

no-op on most terminals; it is active only if

13907

can_change_color() returns 1.</description>

13908

<param name="color_number" optional="0">color_number</param><param name="r" optional="0">r</param><param name="g" optional="0">g</param><param name="b b" optional="0">b b</param>

13909

<insert>init_color(color_number, r, g, b b)</insert><dialog title="Insert init_color">init_color(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

13910

13911

13912

<description>Changes the definition of a color-pair. It takes three arguments: the

13913

number of the color-pair to be changed, the foreground color number,

13914

and the background color number. The value of pair_number must

13915

be between 1 and COLOR_PAIRS - 1 (the 0 color

13916

pair is wired to white on black and cannot be changed). The value of

13917

fg and bg arguments must be between 0 and

13918

COLORS. If the color-pair was previously initialized, the

13919

screen is refreshed and all occurrences of that color-pair are changed

13920

to the new definition.</description>

13921

<param name="pair_number" optional="0">pair_number</param><param name="fg" optional="0">fg</param><param name="bg bg" optional="0">bg bg</param>

13922

<insert>init_pair(pair_number, fg, bg bg)</insert><dialog title="Insert init_pair">init_pair(%0, %1, %2)</dialog><info title="Info window"></info></function>

13923

13924

13925

<description>Initialize the library. Returns a WindowObject which represents

13926

the whole screen. If there is an error opening the terminal,

13927

the underlying curses library may cause the interpreter to exit.</description>

13928

13929

<insert>initscr()</insert><dialog title="Insert initscr">initscr()</dialog><info title="Info window"></info></function>

13930

13931

13932

<description>Returns true if endwin() has been called (that is, the curses library has been deinitialized).</description>

13933

13934

<insert>isendwin()</insert><dialog title="Insert isendwin">isendwin()</dialog><info title="Info window"></info></function>

13935

13936

13937

<description>Return the name of the key numbered k. The name of a key

13938

generating printable ASCII character is the key's character. The name

13939

of a control-key combination is a two-character string consisting of a

13940

caret followed by the corresponding printable ASCII character. The

13941

name of an alt-key combination (128-255) is a string consisting of the

13942

prefix `M-' followed by the name of the corresponding ASCII character.</description>

13943

13944

<insert>keyname(kk)</insert><dialog title="Insert keyname">keyname(%0)</dialog><info title="Info window"></info></function>

13945

13946

13947

<description>Returns the user's current line kill character. Under operating

13948

systems this is a property of the controlling tty of the curses

13949

program, and is not set by the curses library itself.</description>

13950

13951

<insert>killchar()</insert><dialog title="Insert killchar">killchar()</dialog><info title="Info window"></info></function>

13952

13953

13954

<description>Returns a string containing the terminfo long name field describing the current

13955

terminal. The maximum length of a verbose description is 128

13956

characters. It is defined only after the call to

13957

initscr().</description>

13958

13959

<insert>longname()</insert><dialog title="Insert longname">longname()</dialog><info title="Info window"></info></function>

13960

13961

13962

<description>If yes is 1, allow 8-bit characters to be input. If yes is 0, allow only 7-bit chars.</description>

13963

<param name="yesyes" optional="0">yesyes</param>

13964

<insert>meta(yesyes)</insert><dialog title="Insert meta">meta(%0)</dialog><info title="Info window"></info></function>

13965

13966

13967

<description>Sets the maximum time in milliseconds that can elapse between press and

13968

release events in order for them to be recognized as a click, and

13969

returns the previous interval value. The default value is 200 msec,

13970

or one fifth of a second.</description>

13971

<param name="intervalinterval" optional="0">intervalinterval</param>

13972

<insert>mouseinterval(intervalinterval)</insert><dialog title="Insert mouseinterval">mouseinterval(%0)</dialog><info title="Info window"></info></function>

13973

13974

13975

<description>Sets the mouse events to be reported, and returns a tuple

13976

(availmask, oldmask). availmask indicates which of the

13977

specified mouse events can be reported; on complete failure it returns

13978

0. oldmask is the previous value of the given window's mouse

13979

event mask. If this function is never called, no mouse events are

13980

ever reported.</description>

13981

<param name="mousemaskmousemask" optional="0">mousemaskmousemask</param>

13982

<insert>mousemask(mousemaskmousemask)</insert><dialog title="Insert mousemask">mousemask(%0)</dialog><info title="Info window"></info></function>

13983

13984

13985

<description>Sleep for ms milliseconds.</description>

13986

13987

<insert>napms(msms)</insert><dialog title="Insert napms">napms(%0)</dialog><info title="Info window"></info></function>

13988

13989

13990

<description>Creates and returns a pointer to a new pad data structure with the

13991

given number of lines and columns. A pad is returned as a

13992

window object.

13993

A pad is like a window, except that it is not restricted by the screen

13994

size, and is not necessarily associated with a particular part of the

13995

screen. Pads can be used when a large window is needed, and only a

13996

part of the window will be on the screen at one time. Automatic

13997

refreshes of pads (such as from scrolling or echoing of input) do not

13998

occur. The refresh() and noutrefresh() methods of a

13999

pad require 6 arguments to specify the part of the pad to be

14000

displayed and the location on the screen to be used for the display.

14001

The arguments are pminrow, pmincol, sminrow, smincol, smaxrow,

14002

smaxcol; the p arguments refer to the upper left corner of the pad

14003

region to be displayed and the s arguments define a clipping box on

14004

the screen within which the pad region is to be displayed.</description>

14005

<param name="nlines" optional="0">nlines</param><param name="ncols ncols" optional="0">ncols ncols</param>

14006

<insert>newpad(nlines, ncols ncols)</insert><dialog title="Insert newpad">newpad(%0, %1)</dialog><info title="Info window"></info></function>

14007

14008

14009

<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>

14010

<param name="nlines" optional="0">nlines</param><param name="ncols" optional="1">ncols</param><param name="begin_y" optional="1">begin_y</param><param name="begin_x begin_x" optional="1">begin_x begin_x</param>

14011

<insert>newwin(nlines, [ncols], [begin_y], [begin_x begin_x])</insert><dialog title="Insert newwin">newwin(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

14012

14013

14014

<description>Enter newline mode. This mode translates the return key into newline

14015

on input, and translates newline into return and line-feed on output.

14016

Newline mode is initially on.</description>

14017

14018

14019

14020

14021

<description>Leave cbreak mode. Return to normal ``cooked'' mode with line buffering.</description>

14022

14023

<insert>nocbreak()</insert><dialog title="Insert nocbreak">nocbreak()</dialog><info title="Info window"></info></function>

14024

14025

14026

<description>Leave echo mode. Echoing of input characters is turned off.</description>

14027

14028

<insert>noecho()</insert><dialog title="Insert noecho">noecho()</dialog><info title="Info window"></info></function>

14029

14030

14031

<description>Leave newline mode. Disable translation of return into newline on

14032

input, and disable low-level translation of newline into

14033

newline/return on output (but this does not change the behavior of

14034

addch('\n'), which always does the equivalent of return and

14035

line feed on the virtual screen). With translation off, curses can

14036

sometimes speed up vertical motion a little; also, it will be able to

14037

detect the return key on input.</description>

14038

14039

14040

14041

14042

<description>When the noqiflush routine is used, normal flush of input and

14043

output queues associated with the INTR, QUIT and SUSP

14044

characters will not be done. You may want to call

14045

noqiflush() in a signal handler if you want output

14046

to continue as though the interrupt had not occurred, after the

14047

handler exits.</description>

14048

14049

<insert>noqiflush()</insert><dialog title="Insert noqiflush">noqiflush()</dialog><info title="Info window"></info></function>

14050

14051

14052

<description>Leave raw mode. Return to normal ``cooked'' mode with line buffering.</description>

14053

14054

<insert>noraw()</insert><dialog title="Insert noraw">noraw()</dialog><info title="Info window"></info></function>

14055

14056

14057

<description>Returns a tuple (fg, bg) containing the colors for

14058

the requested color pair. The value of pair_number must be

14059

between 0 and COLOR_PAIRS - 1.</description>

14060

<param name="pair_numberpair_number" optional="0">pair_numberpair_number</param>

14061

<insert>pair_content(pair_numberpair_number)</insert><dialog title="Insert pair_content">pair_content(%0)</dialog><info title="Info window"></info></function>

14062

14063

14064

<description>Returns the number of the color-pair set by the attribute value

14065

attr. color_pair() is the counterpart to this

14066

function.</description>

14067

<param name="attrattr" optional="0">attrattr</param>

14068

<insert>pair_number(attrattr)</insert><dialog title="Insert pair_number">pair_number(%0)</dialog><info title="Info window"></info></function>

14069

14070

14071

<description>Equivalent to tputs(str, 1, putchar); emits the value of a

14072

specified terminfo capability for the current terminal. Note that the

14073

output of putp always goes to standard output.</description>

14074

<param name="stringstring" optional="0">stringstring</param>

14075

<insert>putp(stringstring)</insert><dialog title="Insert putp">putp(%0)</dialog><info title="Info window"></info></function>

14076

14077

14078

<description>If flag is false, the effect is the same as calling

14079

noqiflush(). If flag is true, or no argument is

14080

provided, the queues will be flushed when these control characters are

14081

read.</description>

14082

14083

<insert>qiflush(flag)</insert><dialog title="Insert qiflush">qiflush(%0)</dialog><info title="Info window"></info></function>

14084

14085

14086

<description>Enter raw mode. In raw mode, normal line buffering and processing of interrupt, quit, suspend, and flow control keys are

14087

turned off; characters are presented to curses input functions one

14088

by one.</description>

14089

14090

14091

14092

14093

<description>Restores the terminal to ``program'' mode, as previously saved by def_prog_mode().</description>

14094

14095

<insert>reset_prog_mode()</insert><dialog title="Insert reset_prog_mode">reset_prog_mode()</dialog><info title="Info window"></info></function>

14096

14097

14098

<description>Restores the terminal to ``shell'' mode, as previously saved by def_shell_mode().</description>

14099

14100

<insert>reset_shell_mode()</insert><dialog title="Insert reset_shell_mode">reset_shell_mode()</dialog><info title="Info window"></info></function>

14101

14102

14103

<description>Sets the virtual screen cursor to y, x.

14104

If y and x are both -1, then leaveok is set.</description>

14105

14106

<insert>setsyx(y, x x)</insert><dialog title="Insert setsyx">setsyx(%0, %1)</dialog><info title="Info window"></info></function>

14107

14108

14109

<description>Initializes the terminal. termstr is a string giving the

14110

terminal name; if omitted, the value of the TERM environment variable

14111

will be used. fd is the file descriptor to which any

14112

initialization sequences will be sent; if not supplied, the file

14113

descriptor for sys.stdout will be used.</description>

14114

<param name="termstr" optional="0">termstr</param><param name="fd" optional="1">fd</param>

14115

<insert>setupterm(termstr, [fd])</insert><dialog title="Insert setupterm">setupterm(%0, %1)</dialog><info title="Info window"></info></function>

14116

14117

14118

<description>Must be called if the programmer wants to use colors, and before any

14119

other color manipulation routine is called. It is good

14120

practice to call this routine right after initscr().

14121

start_color() initializes eight basic colors (black, red, green, yellow, blue, magenta, cyan, and white), and two global

14122

variables in the curses module, COLORS and

14123

COLOR_PAIRS, containing the maximum number of colors and

14124

color-pairs the terminal can support. It also restores the colors on

14125

the terminal to the values they had when the terminal was just turned

14126

on.</description>

14127

14128

<insert>start_color()</insert><dialog title="Insert start_color">start_color()</dialog><info title="Info window"></info></function>

14129

14130

14131

<description>Returns a logical OR of all video attributes supported by the

14132

terminal. This information is useful when a curses program needs

14133

complete control over the appearance of the screen.</description>

14134

14135

<insert>termattrs()</insert><dialog title="Insert termattrs">termattrs()</dialog><info title="Info window"></info></function>

14136

14137

14138

<description>Returns the value of the environment variable TERM, truncated to 14

14139

characters.</description>

14140

14141

<insert>termname()</insert><dialog title="Insert termname">termname()</dialog><info title="Info window"></info></function>

14142

14143

14144

<description>Returns the value of the Boolean capability corresponding to the

14145

terminfo capability name capname. The value -1 is

14146

returned if capname is not a Boolean capability, or 0 if

14147

it is canceled or absent from the terminal description.</description>

14148

<param name="capnamecapname" optional="0">capnamecapname</param>

14149

<insert>tigetflag(capnamecapname)</insert><dialog title="Insert tigetflag">tigetflag(%0)</dialog><info title="Info window"></info></function>

14150

14151

14152

<description>Returns the value of the numeric capability corresponding to the

14153

terminfo capability name capname. The value -2 is

14154

returned if capname is not a numeric capability, or -1 if

14155

it is canceled or absent from the terminal description.</description>

14156

<param name="capnamecapname" optional="0">capnamecapname</param>

14157

<insert>tigetnum(capnamecapname)</insert><dialog title="Insert tigetnum">tigetnum(%0)</dialog><info title="Info window"></info></function>

14158

14159

14160

<description>Returns the value of the string capability corresponding to the

14161

terminfo capability name capname. None is returned if

14162

capname is not a string capability, or is canceled or absent

14163

from the terminal description.</description>

14164

<param name="capnamecapname" optional="0">capnamecapname</param>

14165

<insert>tigetstr(capnamecapname)</insert><dialog title="Insert tigetstr">tigetstr(%0)</dialog><info title="Info window"></info></function>

14166

14167

14168

<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>

14169

14170

<insert>tparm(str, [...])</insert><dialog title="Insert tparm">tparm(%0, %1)</dialog><info title="Info window"></info></function>

14171

14172

14173

<description>Specifies that the file descriptor fd be used for typeahead

14174

checking. If fd is -1, then no typeahead checking is

14175

done.

14176

The curses library does ``line-breakout optimization'' by looking for

14177

typeahead periodically while updating the screen. If input is found,

14178

and it is coming from a tty, the current update is postponed until

14179

refresh or doupdate is called again, allowing faster response to

14180

commands typed in advance. This function allows specifying a different

14181

file descriptor for typeahead checking.</description>

14182

14183

<insert>typeahead(fdfd)</insert><dialog title="Insert typeahead">typeahead(%0)</dialog><info title="Info window"></info></function>

14184

14185

14186

<description>Returns a string which is a printable representation of the character

14187

ch. Control characters are displayed as a caret followed by the

14188

character, for example as C. Printing

14189

characters are left as they are.</description>

14190

14191

<insert>unctrl(chch)</insert><dialog title="Insert unctrl">unctrl(%0)</dialog><info title="Info window"></info></function>

14192

14193

14194

<description>Push ch so the next getch() will return it.

14195

Only one ch can be pushed before getch()

14196

is called.</description>

14197

14198

<insert>ungetch(chch)</insert><dialog title="Insert ungetch">ungetch(%0)</dialog><info title="Info window"></info></function>

14199

14200

14201

<description>Push a KEY_MOUSE event onto the input queue, associating

14202

the given state data with it.</description>

14203

<param name="id" optional="0">id</param><param name="x" optional="0">x</param><param name="y" optional="0">y</param><param name="z" optional="0">z</param><param name="bstate bstate" optional="0">bstate bstate</param>

14204

<insert>ungetmouse(id, x, y, z, bstate bstate)</insert><dialog title="Insert ungetmouse">ungetmouse(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

14205

14206

14207

<description>If used, this function should be called before initscr() or

14208

newterm are called. When flag is false, the values of

14209

lines and columns specified in the terminfo database will be

14210

used, even if environment variables LINES and

14211

COLUMNS (used by default) are set, or if curses is running in

14212

a window (in which case default behavior would be to use the window

14213

size if LINES and COLUMNS are not set).</description>

14214

<param name="flagflag" optional="0">flagflag</param>

14215

<insert>use_env(flagflag)</insert><dialog title="Insert use_env">use_env(%0)</dialog><info title="Info window"></info></function>

14216

14217

14218

<description>Allow use of default values for colors on terminals supporting this

14219

feature. Use this to support transparency in your

14220

application. The default color is assigned to the color number -1.

14221

After calling this function, init_pair(x, curses.COLOR_RED, -1) initializes, for instance,

14222

color pair x to a red foreground color on the default background.</description>

14223

14224

<insert>use_default_colors()</insert><dialog title="Insert use_default_colors">use_default_colors()</dialog><info title="Info window"></info></function>

14225

14226

</group>

14227

14228

<description>Window objects, as returned by initscr() and

14229

newwin() above, have the

14230

following methods:

14231

</description>

14232

14233

<description>A character means a C character (an

14234

ASCII code), rather then a Python character (a string of length 1).

14235

(This note is true whenever the documentation mentions a character.)

14236

The builtin ord() is handy for conveying strings to codes.

14237

Paint character ch at (y, x) with attributes

14238

attr, overwriting any character previously painter at that

14239

location. By default, the character position and attributes are the

14240

current settings for the window object.</description>

14241

14242

<insert>addch(y, [x], [ch], [attr])</insert><dialog title="Insert addch">addch(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

14243

14244

14245

<description>Paint at most n characters of the string str at (y, x) with attributes

14246

attr, overwriting anything previously on the display.</description>

14247

14248

<insert>addnstr(y, [x], [str], [n], [attr])</insert><dialog title="Insert addnstr">addnstr(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

14249

14250

14251

<description>Paint the string str at (y, x) with attributes

14252

attr, overwriting anything previously on the display.</description>

14253

14254

<insert>addstr(y, [x], [str], [attr])</insert><dialog title="Insert addstr">addstr(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

14255

14256

14257

<description>Remove attribute attr from the ``background'' set applied to all

14258

writes to the current window.</description>

14259

<param name="attrattr" optional="0">attrattr</param>

14260

<insert>attroff(attrattr)</insert><dialog title="Insert attroff">attroff(%0)</dialog><info title="Info window"></info></function>

14261

14262

14263

<description>Add attribute attr from the ``background'' set applied to all

14264

writes to the current window.</description>

14265

<param name="attrattr" optional="0">attrattr</param>

14266

<insert>attron(attrattr)</insert><dialog title="Insert attron">attron(%0)</dialog><info title="Info window"></info></function>

14267

14268

14269

<description>Set the ``background'' set of attributes to attr. This set is

14270

initially 0 (no attributes).</description>

14271

<param name="attrattr" optional="0">attrattr</param>

14272

<insert>attrset(attrattr)</insert><dialog title="Insert attrset">attrset(%0)</dialog><info title="Info window"></info></function>

14273

14274

14275

<description>Sets the background property of the window to the character ch,

14276

with attributes attr. The change is then applied to every

14277

character position in that window:

14278

The attribute of every character in the window is

14279

changed to the new background attribute.

14280

Wherever the former background character appears,

14281

it is changed to the new background character.

14282

</description>

14283

14284

14285

14286

14287

<description>Sets the window's background. A window's background consists of a

14288

character and any combination of attributes. The attribute part of

14289

the background is combined (OR'ed) with all non-blank characters that

14290

are written into the window. Both the character and attribute parts

14291

of the background are combined with the blank characters. The

14292

background becomes a property of the character and moves with the

14293

character through any scrolling and insert/delete line/character

14294

operations.</description>

14295

14296

<insert>bkgdset(ch, [attr])</insert><dialog title="Insert bkgdset">bkgdset(%0, %1)</dialog><info title="Info window"></info></function>

14297

14298

14299

<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

14300

below for more details. The characters can be specified as integers

14301

or as one-character strings.

14302

A 0 value for any parameter will cause the

14303

default character to be used for that parameter. Keyword parameters

14304

can not be used. The defaults are listed in this table:

14305

{l|l|l}{var}{Parameter}{Description}{Default value}

14306

ls{Left side}{ACS_VLINE}

14307

rs{Right side}{ACS_VLINE}

14308

ts{Top}{ACS_HLINE}

14309

bs{Bottom}{ACS_HLINE}

14310

tl{Upper-left corner}{ACS_ULCORNER}

14311

tr{Upper-right corner}{ACS_URCORNER}

14312

bl{Bottom-left corner}{ACS_BLCORNER}

14313

br{Bottom-right corner}{ACS_BRCORNER}

14314

</description>

14315

14316

<insert>border(ls, [rs], [ts], [bs], [tl], [tr], [bl], [br])</insert><dialog title="Insert border">border(%0, %1, %2, %3, %4, %5, %6, %7)</dialog><info title="Info window"></info></function>

14317

14318

14319

<description>Similar to border(), but both ls and rs are

14320

vertch and both ts and {bs} are horch. The default

14321

corner characters are always used by this function.</description>

14322

<param name="vertch" optional="0">vertch</param><param name="horch" optional="1">horch</param>

14323

<insert>box(vertch, [horch])</insert><dialog title="Insert box">box(%0, %1)</dialog><info title="Info window"></info></function>

14324

14325

14326

<description>Like erase(), but also causes the whole window to be repainted

14327

upon next call to refresh().</description>

14328

14329

<insert>clear()</insert><dialog title="Insert clear">clear()</dialog><info title="Info window"></info></function>

14330

14331

14332

<description>If yes is 1, the next call to refresh()

14333

will clear the window completely.</description>

14334

<param name="yesyes" optional="0">yesyes</param>

14335

<insert>clearok(yesyes)</insert><dialog title="Insert clearok">clearok(%0)</dialog><info title="Info window"></info></function>

14336

14337

14338

<description>Erase from cursor to the end of the window: all lines below the cursor

14339

are deleted, and then the equivalent of clrtoeol() is performed.</description>

14340

14341

<insert>clrtobot()</insert><dialog title="Insert clrtobot">clrtobot()</dialog><info title="Info window"></info></function>

14342

14343

14344

<description>Erase from cursor to the end of the line.</description>

14345

14346

<insert>clrtoeol()</insert><dialog title="Insert clrtoeol">clrtoeol()</dialog><info title="Info window"></info></function>

14347

14348

14349

<description>Updates the current cursor position of all the ancestors of the window

14350

to reflect the current cursor position of the window.</description>

14351

14352

<insert>cursyncup()</insert><dialog title="Insert cursyncup">cursyncup()</dialog><info title="Info window"></info></function>

14353

14354

14355

<description>Delete any character at (y, x).</description>

14356

14357

<insert>delch(x, [y])</insert><dialog title="Insert delch">delch(%0, %1)</dialog><info title="Info window"></info></function>

14358

14359

14360

<description>Delete the line under the cursor. All following lines are moved up

14361

by 1 line.</description>

14362

14363

<insert>deleteln()</insert><dialog title="Insert deleteln">deleteln()</dialog><info title="Info window"></info></function>

14364

14365

14366

<description>An abbreviation for ``derive window'', derwin() is the same

14367

as calling subwin(), except that begin_y and

14368

begin_x are relative to the origin of the window, rather than

14369

relative to the entire screen. Returns a window object for the

14370

derived window.</description>

14371

<param name="nlines" optional="0">nlines</param><param name="ncols" optional="1">ncols</param><param name="begin_y" optional="1">begin_y</param><param name="begin_x begin_x" optional="1">begin_x begin_x</param>

14372

<insert>derwin(nlines, [ncols], [begin_y], [begin_x begin_x])</insert><dialog title="Insert derwin">derwin(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

14373

14374

14375

<description>Add character ch with attribute attr, and immediately call refresh() on the window.</description>

14376

14377

<insert>echochar(ch, [attr])</insert><dialog title="Insert echochar">echochar(%0, %1)</dialog><info title="Info window"></info></function>

14378

14379

14380

<description>Tests whether the given pair of screen-relative character-cell

14381

coordinates are enclosed by the given window, returning true or

14382

false. It is useful for determining what subset of the screen

14383

windows enclose the location of a mouse event.</description>

14384

14385

<insert>enclose(y, x x)</insert><dialog title="Insert enclose">enclose(%0, %1)</dialog><info title="Info window"></info></function>

14386

14387

14388

<description>Clear the window.</description>

14389

14390

<insert>erase()</insert><dialog title="Insert erase">erase()</dialog><info title="Info window"></info></function>

14391

14392

14393

<description>Return a tuple (y, x) of co-ordinates of upper-left

14394

corner.</description>

14395

14396

<insert>getbegyx()</insert><dialog title="Insert getbegyx">getbegyx()</dialog><info title="Info window"></info></function>

14397

14398

14399

<description>Get a character. Note that the integer returned does not have to

14400

be in ASCII range: function keys, keypad keys and so on return numbers

14401

higher than 256. In no-delay mode, -1 is returned if there is no input.</description>

14402

14403

<insert>getch(x, [y])</insert><dialog title="Insert getch">getch(%0, %1)</dialog><info title="Info window"></info></function>

14404

14405

14406

<description>Get a character, returning a string instead of an integer, as

14407

getch() does. Function keys, keypad keys and so on return a

14408

multibyte string containing the key name. In no-delay mode, an

14409

exception is raised if there is no input.</description>

14410

14411

<insert>getkey(x, [y])</insert><dialog title="Insert getkey">getkey(%0, %1)</dialog><info title="Info window"></info></function>

14412

14413

14414

<description>Return a tuple (y, x) of the height and width of

14415

the window.</description>

14416

14417

<insert>getmaxyx()</insert><dialog title="Insert getmaxyx">getmaxyx()</dialog><info title="Info window"></info></function>

14418

14419

14420

<description>Returns the beginning coordinates of this window relative to its

14421

parent window into two integer variables y and x. Returns

14422

-1,-1 if this window has no parent.</description>

14423

14424

<insert>getparyx()</insert><dialog title="Insert getparyx">getparyx()</dialog><info title="Info window"></info></function>

14425

14426

14427

<description>Read a string from the user, with primitive line editing capacity.</description>

14428

14429

<insert>getstr(x, [y])</insert><dialog title="Insert getstr">getstr(%0, %1)</dialog><info title="Info window"></info></function>

14430

14431

14432

<description>Return a tuple (y, x) of current cursor position relative to the window's upper-left corner.</description>

14433

14434

<insert>getyx()</insert><dialog title="Insert getyx">getyx()</dialog><info title="Info window"></info></function>

14435

14436

14437

<description>Display a horizontal line starting at (y, x) with

14438

length n consisting of the character ch.</description>

14439

14440

<insert>hline(y, [x], [ch], [n n])</insert><dialog title="Insert hline">hline(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

14441

14442

14443

<description>If flag is false, curses no longer considers using the hardware

14444

insert/delete character feature of the terminal; if flag is

14445

true, use of character insertion and deletion is enabled. When curses

14446

is first initialized, use of character insert/delete is enabled by

14447

default.</description>

14448

<param name="flagflag" optional="0">flagflag</param>

14449

<insert>idcok(flagflag)</insert><dialog title="Insert idcok">idcok(%0)</dialog><info title="Info window"></info></function>

14450

14451

14452

<description>If called with yes equal to 1, curses will try and use

14453

hardware line editing facilities. Otherwise, line insertion/deletion

14454

are disabled.</description>

14455

<param name="yesyes" optional="0">yesyes</param>

14456

<insert>idlok(yesyes)</insert><dialog title="Insert idlok">idlok(%0)</dialog><info title="Info window"></info></function>

14457

14458

14459

<description>If flag is true, any change in the window image

14460

automatically causes the window to be refreshed; you no longer

14461

have to call refresh() yourself. However, it may

14462

degrade performance considerably, due to repeated calls to

14463

wrefresh. This option is disabled by default.</description>

14464

<param name="flagflag" optional="0">flagflag</param>

14465

<insert>immedok(flagflag)</insert><dialog title="Insert immedok">immedok(%0)</dialog><info title="Info window"></info></function>

14466

14467

14468

<description>Return the character at the given position in the window. The bottom

14469

8 bits are the character proper, and upper bits are the attributes.</description>

14470

14471

14472

14473

14474

<description>Paint character ch at (y, x) with attributes

14475

attr, moving the line from position x right by one

14476

character.</description>

14477

14478

<insert>insch(y, [x], [ch], [attr])</insert><dialog title="Insert insch">insch(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

14479

14480

14481

<description>Inserts nlines lines into the specified window above the current

14482

line. The nlines bottom lines are lost. For negative

14483

nlines, delete nlines lines starting with the one under

14484

the cursor, and move the remaining lines up. The bottom nlines

14485

lines are cleared. The current cursor position remains the same.</description>

14486

<param name="nlinesnlines" optional="0">nlinesnlines</param>

14487

<insert>insdelln(nlinesnlines)</insert><dialog title="Insert insdelln">insdelln(%0)</dialog><info title="Info window"></info></function>

14488

14489

14490

<description>Insert a blank line under the cursor. All following lines are moved

14491

down by 1 line.</description>

14492

14493

<insert>insertln()</insert><dialog title="Insert insertln">insertln()</dialog><info title="Info window"></info></function>

14494

14495

14496

<description>Insert a character string (as many characters as will fit on the line)

14497

before the character under the cursor, up to n characters. If n is zero or negative,

14498

the entire string is inserted.

14499

All characters to the right of

14500

the cursor are shifted right, with the rightmost characters on the

14501

line being lost. The cursor position does not change (after moving to

14502

y, x, if specified).</description>

14503

14504

<insert>insnstr(y, [x], [str], [n], [attr])</insert><dialog title="Insert insnstr">insnstr(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

14505

14506

14507

<description>Insert a character string (as many characters as will fit on the line)

14508

before the character under the cursor. All characters to the right of

14509

the cursor are shifted right, with the rightmost characters on the

14510

line being lost. The cursor position does not change (after moving to

14511

y, x, if specified).</description>

14512

14513

<insert>insstr(y, [x], [str], [attr])</insert><dialog title="Insert insstr">insstr(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

14514

14515

14516

<description>Returns a string of characters, extracted from the window starting at

14517

the current cursor position, or at y, x if specified.

14518

Attributes are stripped from the characters. If n is specified,

14519

instr() returns return a string at most n characters

14520

long (exclusive of the trailing NUL).</description>

14521

14522

<insert>instr(y, [x], [n])</insert><dialog title="Insert instr">instr(%0, %1, %2)</dialog><info title="Info window"></info></function>

14523

14524

14525

<description>Returns true if the specified line was modified since the last call to

14526

refresh(); otherwise returns false. Raises a

14527

curses.error exception if line is not valid

14528

for the given window.</description>

14529

14530

<insert>is_linetouched(line)</insert><dialog title="Insert is_linetouched">is_linetouched(%0)</dialog><info title="Info window"></info></function>

14531

14532

14533

<description>Returns true if the specified window was modified since the last call to

14534

refresh(); otherwise returns false.</description>

14535

14536

<insert>is_wintouched()</insert><dialog title="Insert is_wintouched">is_wintouched()</dialog><info title="Info window"></info></function>

14537

14538

14539

<description>If yes is 1, escape sequences generated by some keys (keypad, function keys) will be interpreted by curses.

14540

If yes is 0, escape sequences will be left as is in the input

14541

stream.</description>

14542

<param name="yesyes" optional="0">yesyes</param>

14543

<insert>keypad(yesyes)</insert><dialog title="Insert keypad">keypad(%0)</dialog><info title="Info window"></info></function>

14544

14545

14546

<description>If yes is 1, cursor is left where it is on update, instead of

14547

being at ``cursor position.'' This reduces cursor movement where

14548

possible. If possible the cursor will be made invisible.

14549

If yes is 0, cursor will always be at ``cursor position'' after

14550

an update.</description>

14551

<param name="yesyes" optional="0">yesyes</param>

14552

<insert>leaveok(yesyes)</insert><dialog title="Insert leaveok">leaveok(%0)</dialog><info title="Info window"></info></function>

14553

14554

14555

<description>Move cursor to (new_y, new_x).</description>

14556

14557

14558

14559

14560

<description>Moves the window inside its parent window. The screen-relative

14561

parameters of the window are not changed. This routine is used to

14562

display different parts of the parent window at the same physical

14563

position on the screen.</description>

14564

14565

<insert>mvderwin(y, x x)</insert><dialog title="Insert mvderwin">mvderwin(%0, %1)</dialog><info title="Info window"></info></function>

14566

14567

14568

<description>Move the window so its upper-left corner is at

14569

(new_y, new_x).</description>

14570

14571

<insert>mvwin(new_y, new_x new_x)</insert><dialog title="Insert mvwin">mvwin(%0, %1)</dialog><info title="Info window"></info></function>

14572

14573

14574

<description>If yes is 1, getch() will be non-blocking.</description>

14575

<param name="yesyes" optional="0">yesyes</param>

14576

<insert>nodelay(yesyes)</insert><dialog title="Insert nodelay">nodelay(%0)</dialog><info title="Info window"></info></function>

14577

14578

14579

<description>If yes is 1, escape sequences will not be timed out.

14580

If yes is 0, after a few milliseconds, an escape sequence

14581

will not be interpreted, and will be left in the input stream as is.</description>

14582

<param name="yesyes" optional="0">yesyes</param>

14583

<insert>notimeout(yesyes)</insert><dialog title="Insert notimeout">notimeout(%0)</dialog><info title="Info window"></info></function>

14584

14585

14586

<description>Mark for refresh but wait. This function updates the data structure

14587

representing the desired state of the window, but does not force

14588

an update of the physical screen. To accomplish that, call doupdate().</description>

14589

14590

<insert>noutrefresh()</insert><dialog title="Insert noutrefresh">noutrefresh()</dialog><info title="Info window"></info></function>

14591

14592

14593

<description>Overlay the window on top of destwin. The windows need not be

14594

the same size, only the overlapping region is copied. This copy is

14595

non-destructive, which means that the current background character

14596

does not overwrite the old contents of destwin.

14597

To get fine-grained control over the copied region, the second form

14598

of overlay() can be used. sminrow and smincol are

14599

the upper-left coordinates of the source window, and the other variables

14600

mark a rectangle in the destination window.</description>

14601

<param name="destwin" optional="0">destwin</param><param name="sminrow" optional="1">sminrow</param><param name="smincol" optional="1">smincol</param><param name="dminrow" optional="1">dminrow</param><param name="dmincol" optional="1">dmincol</param><param name="dmaxrow" optional="1">dmaxrow</param><param name="dmaxcol" optional="1">dmaxcol</param>

14602

<insert>overlay(destwin, [sminrow], [smincol], [dminrow], [dmincol], [dmaxrow], [dmaxcol])</insert><dialog title="Insert overlay">overlay(%0, %1, %2, %3, %4, %5, %6)</dialog><info title="Info window"></info></function>

14603

14604

14605

<description>Overwrite the window on top of destwin. The windows need not be

14606

the same size, in which case only the overlapping region is

14607

copied. This copy is destructive, which means that the current

14608

background character overwrites the old contents of destwin.

14609

To get fine-grained control over the copied region, the second form

14610

of overwrite() can be used. sminrow and smincol are

14611

the upper-left coordinates of the source window, the other variables

14612

mark a rectangle in the destination window.</description>

14613

<param name="destwin" optional="0">destwin</param><param name="sminrow" optional="1">sminrow</param><param name="smincol" optional="1">smincol</param><param name="dminrow" optional="1">dminrow</param><param name="dmincol" optional="1">dmincol</param><param name="dmaxrow" optional="1">dmaxrow</param><param name="dmaxcol" optional="1">dmaxcol</param>

14614

<insert>overwrite(destwin, [sminrow], [smincol], [dminrow], [dmincol], [dmaxrow], [dmaxcol])</insert><dialog title="Insert overwrite">overwrite(%0, %1, %2, %3, %4, %5, %6)</dialog><info title="Info window"></info></function>

14615

14616

14617

<description>Writes all data associated with the window into the provided file

14618

object. This information can be later retrieved using the

14619

getwin() function.</description>

14620

<param name="filefile" optional="0">filefile</param>

14621

<insert>putwin(filefile)</insert><dialog title="Insert putwin">putwin(%0)</dialog><info title="Info window"></info></function>

14622

14623

14624

<description>Indicates that the num screen lines, starting at line beg,

14625

are corrupted and should be completely redrawn on the next

14626

refresh() call.</description>

14627

14628

<insert>redrawln(beg, num num)</insert><dialog title="Insert redrawln">redrawln(%0, %1)</dialog><info title="Info window"></info></function>

14629

14630

14631

<description>Touches the entire window, causing it to be completely redrawn on the

14632

next refresh() call.</description>

14633

14634

<insert>redrawwin()</insert><dialog title="Insert redrawwin">redrawwin()</dialog><info title="Info window"></info></function>

14635

14636

14637

<description>Update the display immediately (sync actual screen with previous

14638

drawing/deleting methods).

14639

The 6 optional arguments can only be specified when the window is a

14640

pad created with newpad(). The additional parameters are

14641

needed to indicate what part of the pad and screen are involved.

14642

pminrow and pmincol specify the upper left-hand corner of the

14643

rectangle to be displayed in the pad. sminrow, smincol,

14644

smaxrow, and smaxcol specify the edges of the rectangle to

14645

be displayed on the screen. The lower right-hand corner of the

14646

rectangle to be displayed in the pad is calculated from the screen

14647

coordinates, since the rectangles must be the same size. Both

14648

rectangles must be entirely contained within their respective

14649

structures. Negative values of pminrow, pmincol,

14650

sminrow, or smincol are treated as if they were zero.</description>

14651

<param name="pminrow" optional="0">pminrow</param><param name="pmincol" optional="1">pmincol</param><param name="sminrow" optional="1">sminrow</param><param name="smincol" optional="1">smincol</param><param name="smaxrow" optional="1">smaxrow</param><param name="smaxcol" optional="1">smaxcol</param>

14652

<insert>refresh(pminrow, [pmincol], [sminrow], [smincol], [smaxrow], [smaxcol])</insert><dialog title="Insert refresh">refresh(%0, %1, %2, %3, %4, %5)</dialog><info title="Info window"></info></function>

14653

14654

14655

<description>Scroll the screen or scrolling region upward by lines lines.</description>

14656

<param name="lines" optional="0" default=" 1">lines</param>

14657

<insert>scroll(lines)</insert><dialog title="Insert scroll">scroll(%0)</dialog><info title="Info window"></info></function>

14658

14659

14660

<description>Controls what happens when the cursor of a window is moved off the

14661

edge of the window or scrolling region, either as a result of a

14662

newline action on the bottom line, or typing the last character

14663

of the last line. If flag is false, the cursor is left

14664

on the bottom line. If flag is true, the window is

14665

scrolled up one line. Note that in order to get the physical

14666

scrolling effect on the terminal, it is also necessary to call

14667

idlok().</description>

14668

<param name="flagflag" optional="0">flagflag</param>

14669

<insert>scrollok(flagflag)</insert><dialog title="Insert scrollok">scrollok(%0)</dialog><info title="Info window"></info></function>

14670

14671

14672

<description>Set the scrolling region from line top to line bottom. All

14673

scrolling actions will take place in this region.</description>

14674

<param name="top" optional="0">top</param><param name="bottom bottom" optional="0">bottom bottom</param>

14675

<insert>setscrreg(top, bottom bottom)</insert><dialog title="Insert setscrreg">setscrreg(%0, %1)</dialog><info title="Info window"></info></function>

14676

14677

14678

<description>Turn off the standout attribute. On some terminals this has the

14679

side effect of turning off all attributes.</description>

14680

14681

<insert>standend()</insert><dialog title="Insert standend">standend()</dialog><info title="Info window"></info></function>

14682

14683

14684

<description>Turn on attribute A_STANDOUT.</description>

14685

14686

<insert>standout()</insert><dialog title="Insert standout">standout()</dialog><info title="Info window"></info></function>

14687

14688

14689

<description>Return a sub-window, whose upper-left corner is at

14690

(begin_y, begin_x), and whose width/height is

14691

ncols/nlines.</description>

14692

<param name="nlines" optional="0">nlines</param><param name="ncols" optional="1">ncols</param><param name="begin_y" optional="1">begin_y</param><param name="begin_x begin_x" optional="1">begin_x begin_x</param>

14693

<insert>subpad(nlines, [ncols], [begin_y], [begin_x begin_x])</insert><dialog title="Insert subpad">subpad(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

14694

14695

14696

<description>Return a sub-window, whose upper-left corner is at

14697

(begin_y, begin_x), and whose width/height is

14698

ncols/nlines.

14699

By default, the sub-window will extend from the

14700

specified position to the lower right corner of the window.</description>

14701

<param name="nlines" optional="0">nlines</param><param name="ncols" optional="1">ncols</param><param name="begin_y" optional="1">begin_y</param><param name="begin_x begin_x" optional="1">begin_x begin_x</param>

14702

<insert>subwin(nlines, [ncols], [begin_y], [begin_x begin_x])</insert><dialog title="Insert subwin">subwin(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

14703

14704

14705

<description>Touches each location in the window that has been touched in any of

14706

its ancestor windows. This routine is called by refresh(),

14707

so it should almost never be necessary to call it manually.</description>

14708

14709

<insert>syncdown()</insert><dialog title="Insert syncdown">syncdown()</dialog><info title="Info window"></info></function>

14710

14711

14712

<description>If called with flag set to true, then syncup() is

14713

called automatically whenever there is a change in the window.</description>

14714

<param name="flagflag" optional="0">flagflag</param>

14715

<insert>syncok(flagflag)</insert><dialog title="Insert syncok">syncok(%0)</dialog><info title="Info window"></info></function>

14716

14717

14718

<description>Touches all locations in ancestors of the window that have been changed in the window.</description>

14719

14720

<insert>syncup()</insert><dialog title="Insert syncup">syncup()</dialog><info title="Info window"></info></function>

14721

14722

14723

<description>Sets blocking or non-blocking read behavior for the window. If

14724

delay is negative, blocking read is used (which will wait

14725

indefinitely for input). If delay is zero, then non-blocking

14726

read is used, and -1 will be returned by getch() if no input

14727

is waiting. If delay is positive, then getch() will

14728

block for delay milliseconds, and return -1 if there is still no

14729

input at the end of that time.</description>

14730

<param name="delaydelay" optional="0">delaydelay</param>

14731

<insert>timeout(delaydelay)</insert><dialog title="Insert timeout">timeout(%0)</dialog><info title="Info window"></info></function>

14732

14733

14734

<description>Pretend count lines have been changed, starting with line

14735

start.</description>

14736

<param name="start" optional="0">start</param><param name="count count" optional="0">count count</param>

14737

<insert>touchline(start, count count)</insert><dialog title="Insert touchline">touchline(%0, %1)</dialog><info title="Info window"></info></function>

14738

14739

14740

<description>Pretend the whole window has been changed, for purposes of drawing

14741

optimizations.</description>

14742

14743

<insert>touchwin()</insert><dialog title="Insert touchwin">touchwin()</dialog><info title="Info window"></info></function>

14744

14745

14746

<description>Marks all lines in the window as unchanged since the last call to

14747

refresh().</description>

14748

14749

<insert>untouchwin()</insert><dialog title="Insert untouchwin">untouchwin()</dialog><info title="Info window"></info></function>

14750

14751

14752

<description>Display a vertical line starting at (y, x) with

14753

length n consisting of the character ch.</description>

14754

14755

<insert>vline(y, [x], [ch], [n n])</insert><dialog title="Insert vline">vline(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

14756

14757

</group>

14758

14759

<description>The curses module defines the following data members:

14760

{ERR}

14761

Some curses routines that return an integer, such as getch(), return ERR upon failure. {OK}

14762

Some curses routines that return an integer, such as napms(), return OK upon success. {version}

14763

A string representing the current version of the module. Also available as __version__.

14764

Several constants are available to specify character cell attributes:

14765

{l|l}{code}{Attribute}{Meaning}

14766

A_ALTCHARSET{Alternate character set mode.}

14767

A_BLINK{Blink mode.}

14768

A_BOLD{Bold mode.}

14769

A_DIM{Dim mode.}

14770

A_NORMAL{Normal attribute.}

14771

A_STANDOUT{Standout mode.}

14772

A_UNDERLINE{Underline mode.}

14773

Keys are referred to by integer constants with names starting with KEY_. The exact keycaps available are system dependent.

14774

% XXX this table is far too large!

14775

% XXX should this table be alphabetized?

14776

{l|l}{code}{Key constant}{Key}

14777

KEY_MIN{Minimum key value}

14778

KEY_BREAK{ Break key (unreliable) }

14779

KEY_DOWN{ Down-arrow }

14780

KEY_UP{ Up-arrow }

14781

KEY_LEFT{ Left-arrow }

14782

KEY_RIGHT{ Right-arrow }

14783

KEY_HOME{ Home key (upward+left arrow) }

14784

KEY_BACKSPACE{ Backspace (unreliable) }

14785

KEY_F0{ Function keys. Up to 64 function keys are supported. }

14786

KEY_Fn{ Value of function key n }

14787

KEY_DL{ Delete line }

14788

KEY_IL{ Insert line }

14789

KEY_DC{ Delete character }

14790

KEY_IC{ Insert char or enter insert mode }

14791

KEY_EIC{ Exit insert char mode }

14792

KEY_CLEAR{ Clear screen }

14793

KEY_EOS{ Clear to end of screen }

14794

KEY_EOL{ Clear to end of line }

14795

KEY_SF{ Scroll 1 line forward }

14796

KEY_SR{ Scroll 1 line backward (reverse) }

14797

KEY_NPAGE{ Next page }

14798

KEY_PPAGE{ Previous page }

14799

KEY_STAB{ Set tab }

14800

KEY_CTAB{ Clear tab }

14801

KEY_CATAB{ Clear all tabs }

14802

KEY_ENTER{ Enter or send (unreliable) }

14803

KEY_SRESET{ Soft (partial) reset (unreliable) }

14804

KEY_RESET{ Reset or hard reset (unreliable) }

14805

KEY_PRINT{ Print }

14806

KEY_LL{ Home down or bottom (lower left) }

14807

KEY_A1{ Upper left of keypad }

14808

KEY_A3{ Upper right of keypad }

14809

KEY_B2{ Center of keypad }

14810

KEY_C1{ Lower left of keypad }

14811

KEY_C3{ Lower right of keypad }

14812

KEY_BTAB{ Back tab }

14813

KEY_BEG{ Beg (beginning) }

14814

KEY_CANCEL{ Cancel }

14815

KEY_CLOSE{ Close }

14816

KEY_COMMAND{ Cmd (command) }

14817

KEY_COPY{ Copy }

14818

KEY_CREATE{ Create }

14819

KEY_END{ End }

14820

KEY_EXIT{ Exit }

14821

KEY_FIND{ Find }

14822

KEY_HELP{ Help }

14823

KEY_MARK{ Mark }

14824

KEY_MESSAGE{ Message }

14825

KEY_MOVE{ Move }

14826

KEY_NEXT{ Next }

14827

KEY_OPEN{ Open }

14828

KEY_OPTIONS{ Options }

14829

KEY_PREVIOUS{ Prev (previous) }

14830

KEY_REDO{ Redo }

14831

KEY_REFERENCE{ Ref (reference) }

14832

KEY_REFRESH{ Refresh }

14833

KEY_REPLACE{ Replace }

14834

KEY_RESTART{ Restart }

14835

KEY_RESUME{ Resume }

14836

KEY_SAVE{ Save }

14837

KEY_SBEG{ Shifted Beg (beginning) }

14838

KEY_SCANCEL{ Shifted Cancel }

14839

KEY_SCOMMAND{ Shifted Command }

14840

KEY_SCOPY{ Shifted Copy }

14841

KEY_SCREATE{ Shifted Create }

14842

KEY_SDC{ Shifted Delete char }

14843

KEY_SDL{ Shifted Delete line }

14844

KEY_SELECT{ Select }

14845

KEY_SEND{ Shifted End }

14846

KEY_SEOL{ Shifted Clear line }

14847

KEY_SEXIT{ Shifted Dxit }

14848

KEY_SFIND{ Shifted Find }

14849

KEY_SHELP{ Shifted Help }

14850

KEY_SHOME{ Shifted Home }

14851

KEY_SIC{ Shifted Input }

14852

KEY_SLEFT{ Shifted Left arrow }

14853

KEY_SMESSAGE{ Shifted Message }

14854

KEY_SMOVE{ Shifted Move }

14855

KEY_SNEXT{ Shifted Next }

14856

KEY_SOPTIONS{ Shifted Options }

14857

KEY_SPREVIOUS{ Shifted Prev }

14858

KEY_SPRINT{ Shifted Print }

14859

KEY_SREDO{ Shifted Redo }

14860

KEY_SREPLACE{ Shifted Replace }

14861

KEY_SRIGHT{ Shifted Right arrow }

14862

KEY_SRSUME{ Shifted Resume }

14863

KEY_SSAVE{ Shifted Save }

14864

KEY_SSUSPEND{ Shifted Suspend }

14865

KEY_SUNDO{ Shifted Undo }

14866

KEY_SUSPEND{ Suspend }

14867

KEY_UNDO{ Undo }

14868

KEY_MOUSE{ Mouse event has occurred }

14869

KEY_RESIZE{ Terminal resize event }

14870

KEY_MAX{Maximum key value}

14871

On VT100s and their software emulations, such as X terminal emulators,

14872

there are normally at least four function keys (KEY_F1,

14873

KEY_F2, KEY_F3, KEY_F4) available,

14874

and the arrow keys mapped to KEY_UP, KEY_DOWN,

14875

KEY_LEFT and KEY_RIGHT in the obvious way. If

14876

your machine has a PC keybboard, it is safe to expect arrow keys and

14877

twelve function keys (older PC keyboards may have only ten function

14878

keys); also, the following keypad mappings are standard:

14879

{l|l}{kbd}{Keycap}{Constant}

14880

Insert{KEY_IC}

14881

Delete{KEY_DC}

14882

Home{KEY_HOME}

14883

End{KEY_END}

14884

Page Up{KEY_NPAGE}

14885

Page Down{KEY_PPAGE}

14886

The following table lists characters from the alternate character set.

14887

These are inherited from the VT100 terminal, and will generally be available on software emulations such as X terminals. When there

14888

is no graphic available, curses falls back on a crude printable ASCII

14889

approximation.

14890

These are available only after initscr() has been called.

14891

{l|l}{code}{ACS code}{Meaning}

14892

ACS_BBSS{alternate name for upper right corner}

14893

ACS_BLOCK{solid square block}

14894

ACS_BOARD{board of squares}

14895

ACS_BSBS{alternate name for horizontal line}

14896

ACS_BSSB{alternate name for upper left corner}

14897

ACS_BSSS{alternate name for top tee}

14898

ACS_BTEE{bottom tee}

14899

ACS_BULLET{bullet}

14900

ACS_CKBOARD{checker board (stipple)}

14901

ACS_DARROW{arrow pointing down}

14902

ACS_DEGREE{degree symbol}

14903

ACS_DIAMOND{diamond}

14904

ACS_GEQUAL{greater-than-or-equal-to}

14905

ACS_HLINE{horizontal line}

14906

ACS_LANTERN{lantern symbol}

14907

ACS_LARROW{left arrow}

14908

ACS_LEQUAL{less-than-or-equal-to}

14909

ACS_LLCORNER{lower left-hand corner}

14910

ACS_LRCORNER{lower right-hand corner}

14911

ACS_LTEE{left tee}

14912

ACS_NEQUAL{not-equal sign}

14913

ACS_PI{letter pi}

14914

ACS_PLMINUS{plus-or-minus sign}

14915

ACS_PLUS{big plus sign}

14916

ACS_RARROW{right arrow}

14917

ACS_RTEE{right tee}

14918

ACS_S1{scan line 1}

14919

ACS_S3{scan line 3}

14920

ACS_S7{scan line 7}

14921

ACS_S9{scan line 9}

14922

ACS_SBBS{alternate name for lower right corner}

14923

ACS_SBSB{alternate name for vertical line}

14924

ACS_SBSS{alternate name for right tee}

14925

ACS_SSBB{alternate name for lower left corner}

14926

ACS_SSBS{alternate name for bottom tee}

14927

ACS_SSSB{alternate name for left tee}

14928

ACS_SSSS{alternate name for crossover or big plus}

14929

ACS_STERLING{pound sterling}

14930

ACS_TTEE{top tee}

14931

ACS_UARROW{up arrow}

14932

ACS_ULCORNER{upper left corner}

14933

ACS_URCORNER{upper right corner}

14934

ACS_VLINE{vertical line}

14935

The following table lists the predefined colors:

14936

{l|l}{code}{Constant}{Color}

14937

COLOR_BLACK{Black}

14938

COLOR_BLUE{Blue}

14939

COLOR_CYAN{Cyan (light greenish blue)}

14940

COLOR_GREEN{Green}

14941

COLOR_MAGENTA{Magenta (purplish red)}

14942

COLOR_RED{Red}

14943

COLOR_WHITE{White}

14944

COLOR_YELLOW{Yellow}

14945

curses.textpad ---

14946

Text input widget for curses programs

14947

Emacs-like input editing in a curses window.

14948

New in version 1.6

14949

The curses.textpad module provides a Textbox class

14950

that handles elementary text editing in a curses window, supporting a

14951

set of keybindings resembling those of Emacs (thus, also of Netscape

14952

Navigator, BBedit 6.x, FrameMaker, and many other programs). The

14953

module also provides a rectangle-drawing function useful for framing

14954

text boxes or for other purposes.

14955

The module curses.textpad defines the following function:

14956

</description>

14957

14958

<description>Draw a rectangle. The first argument must be a window object; the

14959

remaining arguments are coordinates relative to that window. The

14960

second and third arguments are the y and x coordinates of the upper

14961

left hand corner of the rectangle To be drawn; the fourth and fifth

14962

arguments are the y and x coordinates of the lower right hand corner.

14963

The rectangle will be drawn using VT100/IBM PC forms characters on

14964

terminals that make this possible (including xterm and most other

14965

software terminal emulators). Otherwise it will be drawn with ASCII dashes, vertical bars, and plus signs.</description>

14966

14967

<insert>rectangle(win, uly, ulx, lry, lrx lrx)</insert><dialog title="Insert rectangle">rectangle(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

14968

14969

</group>

14970

14971

<description>You can instantiate a Textbox object as follows:

14972

</description>

14973

14974

<description>Return a textbox widget object. The win argument should be a

14975

curses WindowObject in which the textbox is to be contained.

14976

The edit cursor of the textbox is initially located at the upper left

14977

hand corner of the containin window, with coordinates (0, 0).

14978

The instance's stripspaces flag is initially on.</description>

14979

<param name="winwin" optional="0">winwin</param>

14980

<insert>Textbox(winwin)</insert><dialog title="Insert Textbox">Textbox(%0)</dialog><info title="Info window"></info></function>

14981

14982

14983

<description>This is the entry point you will normally use. It accepts editing

14984

keystrokes until one of the termination keystrokes is entered. If

14985

validator is supplied, it must be a function. It will be called

14986

for each keystroke entered with the keystroke as a parameter; command

14987

dispatch is done on the result. This method returns the window

14988

contents as a string; whether blanks in the window are included is

14989

affected by the stripspaces member.</description>

14990

<param name="validator" optional="0">validator</param>

14991

<insert>edit(validator)</insert><dialog title="Insert edit">edit(%0)</dialog><info title="Info window"></info></function>

14992

14993

14994

<description>Process a single command keystroke. Here are the supported special

14995

keystrokes: {l|l}{kbd}{Keystroke}{Action}

14996

Control-A{Go to left edge of window.}

14997

Control-B{Cursor left, wrapping to previous line if appropriate.}

14998

Control-D{Delete character under cursor.}

14999

Control-E{Go to right edge (stripspaces off) or end of line

15000

(stripspaces on).}

15001

Control-F{Cursor right, wrapping to next line when appropriate.}

15002

Control-G{Terminate, returning the window contents.}

15003

Control-H{Delete character backward.}

15004

Control-J{Terminate if the window is 1 line, otherwise

15005

insert newline.}

15006

Control-K{If line is blank, delete it, otherwise clear to

15007

end of line.}

15008

Control-L{Refresh screen.}

15009

Control-N{Cursor down; move down one line.}

15010

Control-O{Insert a blank line at cursor location.}

15011

Control-P{Cursor up; move up one line.}

15012

Move operations do nothing if the cursor is at an edge where the

15013

movement is not possible. The following synonyms are supported where

15014

possible:

15015

{l|l}{constant}{Constant}{Keystroke}

15016

KEY_LEFT{Control-B}

15017

KEY_RIGHT{Control-F}

15018

KEY_UP{Control-P}

15019

KEY_DOWN{Control-N}

15020

KEY_BACKSPACE{Control-h}

15021

All other keystrokes are treated as a command to insert the given

15022

character and move right (with line wrapping).</description>

15023

15024

<insert>do_command(chch)</insert><dialog title="Insert do_command">do_command(%0)</dialog><info title="Info window"></info></function>

15025

15026

15027

<description>This method returns the window contents as a string; whether blanks in

15028

the window are included is affected by the stripspaces

15029

member.</description>

15030

15031

<insert>gather()</insert><dialog title="Insert gather">gather()</dialog><info title="Info window"></info></function>

15032

15033

15034

<description>Wrapper function that initializes curses and calls another function,

15035

func, restoring normal keyboard/screen behavior on error.

15036

The callable object func is then passed the main window 'stdscr'

15037

as its first argument, followed by any other arguments passed to

15038

wrapper().</description>

15039

<param name="func" optional="0">func</param><param name="moreargsmoreargs" optional="0">moreargsmoreargs</param>

15040

<insert>wrapper(func, moreargsmoreargs)</insert><dialog title="Insert wrapper">wrapper(%0, %1)</dialog><info title="Info window"></info></function>

15041

15042

</group>

15043

</group>

15044

15045

<description>Constants and set-membership functions for

15046

.

15047

New in version 1.6

15048

The curses.ascii module supplies name constants for

15049

ASCII characters and functions to test membership in various

15050

ASCII character classes. The constants supplied are names for

15051

control characters as follows:

15052

{l|l}{constant}{Name}{Meaning}

15053

NUL{}

15054

SOH{Start of heading, console interrupt}

15055

STX{Start of text}

15056

ETX{End of text}

15057

EOT{End of transmission}

15058

ENQ{Enquiry, goes with ACK flow control}

15059

ACK{Acknowledgement}

15060

BEL{Bell}

15061

BS{Backspace}

15062

TAB{Tab}

15063

HT{Alias for TAB: ``Horizontal tab''}

15064

LF{Line feed}

15065

NL{Alias for LF: ``New line''}

15066

VT{Vertical tab}

15067

FF{Form feed}

15068

CR{Carriage return}

15069

SO{Shift-out, begin alternate character set}

15070

SI{Shift-in, resume default character set}

15071

DLE{Data-link escape}

15072

DC1{XON, for flow control}

15073

DC2{Device control 2, block-mode flow control}

15074

DC3{XOFF, for flow control}

15075

DC4{Device control 4}

15076

NAK{Negative acknowledgement}

15077

SYN{Synchronous idle}

15078

ETB{End transmission block}

15079

CAN{Cancel}

15080

EM{End of medium}

15081

SUB{Substitute}

15082

ESC{Escape}

15083

FS{File separator}

15084

GS{Group separator}

15085

RS{Record separator, block-mode terminator}

15086

US{Unit separator}

15087

SP{Space}

15088

DEL{Delete}

15089

Note that many of these have little practical significance in modern

15090

usage. The mnemonics derive from teleprinter conventions that predate

15091

digital computers.

15092

The module supplies the following functions, patterned on those in the

15093

standard C library:

15094

</description>

15095

15096

<description>Checks for an ASCII alphanumeric character; it is equivalent to

15097

isalpha(c) or isdigit(c).</description>

15098

15099

<insert>isalnum(cc)</insert><dialog title="Insert isalnum">isalnum(%0)</dialog><info title="Info window"></info></function>

15100

15101

15102

<description>Checks for an ASCII alphabetic character; it is equivalent to

15103

isupper(c) or islower(c).</description>

15104

15105

<insert>isalpha(cc)</insert><dialog title="Insert isalpha">isalpha(%0)</dialog><info title="Info window"></info></function>

15106

15107

15108

<description>Checks for a character value that fits in the 7-bit ASCII set.</description>

15109

15110

<insert>isascii(cc)</insert><dialog title="Insert isascii">isascii(%0)</dialog><info title="Info window"></info></function>

15111

15112

15113

<description>Checks for an ASCII whitespace character.</description>

15114

15115

<insert>isblank(cc)</insert><dialog title="Insert isblank">isblank(%0)</dialog><info title="Info window"></info></function>

15116

15117

15118

<description>Checks for an ASCII control character (in the range 0x00 to 0x1f).</description>

15119

15120

<insert>iscntrl(cc)</insert><dialog title="Insert iscntrl">iscntrl(%0)</dialog><info title="Info window"></info></function>

15121

15122

15123

<description>Checks for an ASCII decimal digit, 0 through

15124

9. This is equivalent to c in string.digits.</description>

15125

15126

<insert>isdigit(cc)</insert><dialog title="Insert isdigit">isdigit(%0)</dialog><info title="Info window"></info></function>

15127

15128

15129

<description>Checks for ASCII any printable character except space.</description>

15130

15131

<insert>isgraph(cc)</insert><dialog title="Insert isgraph">isgraph(%0)</dialog><info title="Info window"></info></function>

15132

15133

15134

<description>Checks for an ASCII lower-case character.</description>

15135

15136

<insert>islower(cc)</insert><dialog title="Insert islower">islower(%0)</dialog><info title="Info window"></info></function>

15137

15138

15139

<description>Checks for any ASCII printable character including space.</description>

15140

15141

<insert>isprint(cc)</insert><dialog title="Insert isprint">isprint(%0)</dialog><info title="Info window"></info></function>

15142

15143

15144

<description>Checks for any printable ASCII character which is not a space or an

15145

alphanumeric character.</description>

15146

15147

<insert>ispunct(cc)</insert><dialog title="Insert ispunct">ispunct(%0)</dialog><info title="Info window"></info></function>

15148

15149

15150

<description>Checks for ASCII white-space characters; space, line feed,

15151

carriage return, form feed, horizontal tab, vertical tab.</description>

15152

15153

<insert>isspace(cc)</insert><dialog title="Insert isspace">isspace(%0)</dialog><info title="Info window"></info></function>

15154

15155

15156

<description>Checks for an ASCII uppercase letter.</description>

15157

15158

<insert>isupper(cc)</insert><dialog title="Insert isupper">isupper(%0)</dialog><info title="Info window"></info></function>

15159

15160

15161

<description>Checks for an ASCII hexadecimal digit. This is equivalent to

15162

c in string.hexdigits.</description>

15163

15164

<insert>isxdigit(cc)</insert><dialog title="Insert isxdigit">isxdigit(%0)</dialog><info title="Info window"></info></function>

15165

15166

15167

<description>Checks for an ASCII control character (ordinal values 0 to 31).</description>

15168

15169

<insert>isctrl(cc)</insert><dialog title="Insert isctrl">isctrl(%0)</dialog><info title="Info window"></info></function>

15170

15171

15172

<description>Checks for a non-ASCII character (ordinal values 0x80 and above).</description>

15173

15174

<insert>ismeta(cc)</insert><dialog title="Insert ismeta">ismeta(%0)</dialog><info title="Info window"></info></function>

15175

15176

15177

<description>Return the ASCII value corresponding to the low 7 bits of c.</description>

15178

15179

<insert>ascii(cc)</insert><dialog title="Insert ascii">ascii(%0)</dialog><info title="Info window"></info></function>

15180

15181

15182

<description>Return the control character corresponding to the given character

15183

(the character bit value is bitwise-anded with 0x1f).</description>

15184

15185

15186

15187

15188

<description>Return the 8-bit character corresponding to the given ASCII character

15189

(the character bit value is bitwise-ored with 0x80).</description>

15190

15191

15192

15193

15194

<description>Return a string representation of the ASCII character c. If

15195

c is printable, this string is the character itself. If the

15196

character is a control character (0x00-0x1f) the string consists of a

15197

caret (^) followed by the corresponding uppercase letter.

15198

If the character is an ASCII delete (0x7f) the string is

15199

''. If the character has its meta bit (0x80) set, the meta

15200

bit is stripped, the preceding rules applied, and

15201

! prepended to the result.</description>

15202

15203

<insert>unctrl(cc)</insert><dialog title="Insert unctrl">unctrl(%0)</dialog><info title="Info window"></info></function>

15204

15205

</group>

15206

15207

<description>A panel stack extension that adds depth to curses windows.

15208

Panels are windows with the added feature of depth, so they can be

15209

stacked on top of each other, and only the visible portions of

15210

each window will be displayed. Panels can be added, moved up

15211

or down in the stack, and removed. </description>

15212

15213

<description>The module curses.panel defines the following functions:

15214

</description>

15215

15216

<description>Returns the bottom panel in the panel stack.</description>

15217

15218

<insert>bottom_panel()</insert><dialog title="Insert bottom_panel">bottom_panel()</dialog><info title="Info window"></info></function>

15219

15220

15221

<description>Returns a panel object, associating it with the given window win.</description>

15222

<param name="winwin" optional="0">winwin</param>

15223

<insert>new_panel(winwin)</insert><dialog title="Insert new_panel">new_panel(%0)</dialog><info title="Info window"></info></function>

15224

15225

15226

<description>Returns the top panel in the panel stack.</description>

15227

15228

<insert>top_panel()</insert><dialog title="Insert top_panel">top_panel()</dialog><info title="Info window"></info></function>

15229

15230

15231

<description>Updates the virtual screen after changes in the panel stack. This does

15232

not call curses.doupdate(), so you'll have to do this yourself.</description>

15233

15234

<insert>update_panels()</insert><dialog title="Insert update_panels">update_panels()</dialog><info title="Info window"></info></function>

15235

15236

</group>

15237

15238

<description>Panel objects, as returned by new_panel() above, are windows

15239

with a stacking order. There's always a window associated with a

15240

panel which determines the content, while the panel methods are

15241

responsible for the window's depth in the panel stack.

15242

Panel objects have the following methods:

15243

</description>

15244

15245

<description>Returns the panel above the current panel.</description>

15246

15247

<insert>above()</insert><dialog title="Insert above">above()</dialog><info title="Info window"></info></function>

15248

15249

15250

<description>Returns the panel below the current panel.</description>

15251

15252

<insert>below()</insert><dialog title="Insert below">below()</dialog><info title="Info window"></info></function>

15253

15254

15255

<description>Push the panel to the bottom of the stack.</description>

15256

15257

<insert>bottom()</insert><dialog title="Insert bottom">bottom()</dialog><info title="Info window"></info></function>

15258

15259

15260

<description>Returns true if the panel is hidden (not visible), false otherwise.</description>

15261

15262

<insert>hidden()</insert><dialog title="Insert hidden">hidden()</dialog><info title="Info window"></info></function>

15263

15264

15265

<description>Hide the panel. This does not delete the object, it just makes the

15266

window on screen invisible.</description>

15267

15268

15269

15270

15271

<description>Move the panel to the screen coordinates (y, x).</description>

15272

15273

15274

15275

15276

<description>Change the window associated with the panel to the window win.</description>

15277

<param name="winwin" optional="0">winwin</param>

15278

<insert>replace(winwin)</insert><dialog title="Insert replace">replace(%0)</dialog><info title="Info window"></info></function>

15279

15280

15281

<description>Set the panel's user pointer to obj. This is used to associate an

15282

arbitrary piece of data with the panel, and can be any Python object.</description>

15283

<param name="objobj" optional="0">objobj</param>

15284

<insert>set_userptr(objobj)</insert><dialog title="Insert set_userptr">set_userptr(%0)</dialog><info title="Info window"></info></function>

15285

15286

15287

<description>Display the panel (which might have been hidden).</description>

15288

15289

15290

15291

15292

<description>Push panel to the top of the stack.</description>

15293

15294

15295

15296

15297

<description>Returns the user pointer for the panel. This might be any Python object.</description>

15298

15299

<insert>userptr()</insert><dialog title="Insert userptr">userptr()</dialog><info title="Info window"></info></function>

15300

15301

15302

<description>Returns the window object associated with the panel.</description>

15303

15304

<insert>window()</insert><dialog title="Insert window">window()</dialog><info title="Info window"></info></function>

15305

15306

</group>

15307

</group>

15308

15309

<description>Portable parser for command line options; support both

15310

short and long option names.

15311

This module helps scripts to parse the command line arguments in

15312

sys.argv.

15313

It supports the same conventions as the getopt()

15314

function (including the special meanings of arguments of the form

15315

`-' and `--').

15316

% That's to fool latex2html into leaving the two hyphens alone!

15317

Long options similar to those supported by

15318

GNU software may be used as well via an optional third argument.

15319

This module provides a single function and an exception:

15320

</description>

15321

15322

<description>Parses command line options and parameter list. args is the

15323

argument list to be parsed, without the leading reference to the

15324

running program. Typically, this means sys.argv[1:].

15325

options is the string of option letters that the script wants to

15326

recognize, with options that require an argument followed by a colon

15327

(:; i.e., the same format that getopt() uses).

15328

Unlike GNU getopt(), after a non-option

15329

argument, all further arguments are considered also non-options.

15330

This is similar to the way non-GNU systems work.

15331

long_options, if specified, must be a list of strings with the

15332

names of the long options which should be supported. The leading

15333

'--' characters should not be included in the option

15334

name. Long options which require an argument should be followed by an

15335

equal sign (=). To accept only long options,

15336

options should be an empty string. Long options on the command

15337

line can be recognized so long as they provide a prefix of the option

15338

name that matches exactly one of the accepted options. For example,

15339

it long_options is ['foo', 'frob'], the option

15340

fo will match as foo, but

15341

f will not match uniquely, so GetoptError

15342

will be raised.

15343

The return value consists of two elements: the first is a list of

15344

(option, value) pairs; the second is the list of

15345

program arguments left after the option list was stripped (this is a

15346

trailing slice of args). Each option-and-value pair returned

15347

has the option as its first element, prefixed with a hyphen for short

15348

options (e.g., '-x') or two hyphens for long options (e.g.,

15349

'--long-option'), and the option argument as its second

15350

element, or an empty string if the option has no argument. The

15351

options occur in the list in the same order in which they were found,

15352

thus allowing multiple occurrences. Long and short options may be

15353

mixed.</description>

15354

<param name="args" optional="0">args</param><param name="options" optional="0">options</param><param name="long_options" optional="1">long_options</param>

15355

<insert>getopt(args, options, [long_options])</insert><dialog title="Insert getopt">getopt(%0, %1, %2)</dialog><info title="Info window"></info></function>

15356

15357

15358

<description>This function works like getopt(), except that GNU style

15359

scanning mode is used by default. This means that option and

15360

non-option arguments may be intermixed. The getopt()

15361

function stops processing options as soon as a non-option argument is

15362

encountered.

15363

If the first character of the option string is `+', or if the

15364

environment variable POSIXLY_CORRECT is set, then option processing

15365

stops as soon as a non-option argument is encountered.</description>

15366

<param name="args" optional="0">args</param><param name="options" optional="0">options</param><param name="long_options" optional="1">long_options</param>

15367

<insert>gnu_getopt(args, options, [long_options])</insert><dialog title="Insert gnu_getopt">gnu_getopt(%0, %1, %2)</dialog><info title="Info window"></info></function>

15368

15369

</group>

15370

15371

<description>Powerful, flexible, extensible, easy-to-use command-line

15372

parsing library.

15373

New in version 2.3

15374

The optparse module is a powerful, flexible, extensible,

15375

easy-to-use command-line parsing library for Python. Using

15376

optparse, you can add intelligent, sophisticated handling of

15377

command-line options to your scripts with very little overhead.

15378

Here's an example of using optparse to add some command-line

15379

options to a simple script:

15380

from optparse import OptionParser

15381

parser = OptionParser()

15382

parser.add_option("-f", "--file", dest="filename",

15383

help="write report to FILE", metavar="FILE")

15384

parser.add_option("-q", "--quiet",

15385

action="store_false", dest="verbose", default=True,

15386

help="don't print status messages to stdout")

15387

(options, args) = parser.parse_args()

15388

With these few lines of code, users of your script can now do the

15389

``usual thing'' on the command-line:

15390

$ <yourscript> -f outfile --quiet

15391

$ <yourscript> -qfoutfile

15392

$ <yourscript> --file=outfile -q

15393

$ <yourscript> --quiet --file outfile

15394

(All of these result in options.filename == "outfile" and

15395

options.verbose == False, just as you might expect.)

15396

Even niftier, users can run one of

15397

$ <yourscript> -h

15398

$ <yourscript> --help

15399

and optparse will print out a brief summary of your script's

15400

options:

15401

usage: <yourscript> [options]

15402

options:

15403

-h, --help show this help message and exit

15404

-fFILE, --file=FILE write report to FILE

15405

-q, --quiet don't print status messages to stdout

15406

That's just a taste of the flexibility optparse gives you in

15407

parsing your command-line.

15408

</description>

15409

15410

<description>The purpose of optparse is to make it very easy to provide the

15411

most standard, obvious, straightforward, and user-friendly user

15412

interface for command-line programs. The optparse

15413

philosophy is heavily influenced by the and GNU toolkits, and

15414

this section is meant to explain that philosophy.

15415

Terminology

15416

First, we need to establish some terminology.

15417

argument

15418

a chunk of text that a user enters on the command-line, and that the

15419

shell passes to execl() or execv(). In

15420

Python, arguments are elements of

15421

sys.argv[1:]. (sys.argv[0] is the name of the program

15422

being executed; in the context of parsing arguments, it's not very

15423

important.) shells also use the term ``word''.

15424

It is occasionally desirable to use an argument list other than

15425

sys.argv[1:], so you should read ``argument'' as ``an element of

15426

sys.argv[1:], or of some other list provided as a substitute for

15427

sys.argv[1:]''.

15428

option

15429

an argument used to supply extra information to guide or customize

15430

the execution of a program. There are many different syntaxes for

15431

options; the traditional syntax is - followed by a

15432

single letter, e.g. -x or -F. Also,

15433

traditional syntax allows multiple options to be merged into a

15434

single argument, e.g. -x -F is equivalent to

15435

-xF. The GNU project introduced followed by a series of hyphen-separated words,

15436

e.g. file or dry-run. These are

15437

the only two option syntaxes provided by optparse.

15438

Some other option syntaxes that the world has seen include:

15439

a hyphen followed by a few letters, e.g. -pf (this is

15440

not the same as multiple options merged into a single

15441

argument.)

15442

a hyphen followed by a whole word, e.g. -file (this is

15443

technically equivalent to the previous syntax, but they aren't

15444

usually seen in the same program.)

15445

a plus sign followed by a single letter, or a few letters,

15446

or a word, e.g. +f, +rgb.

15447

a slash followed by a letter, or a few letters, or a word, e.g.

15448

/f, /file.

15449

optparse does not support these option syntaxes, and it never

15450

will. (If you really want to use one of those option syntaxes, you'll

15451

have to subclass OptionParser and override all the difficult

15452

bits. But please don't! optparse does things the traditional

15453

/GNU way deliberately; the first three are non-standard anywhere,

15454

and the last one makes sense only if you're exclusively targeting

15455

MS-DOS/Windows and/or VMS.)

15456

option argument

15457

an argument that follows an option, is closely associated with that

15458

option, and is consumed from the argument list when the option is.

15459

Often, option arguments may also be included in the same argument as

15460

the option, e.g. :

15461

["-f", "foo"]

15462

may be equivalent to:

15463

["-ffoo"]

15464

(optparse supports this syntax.)

15465

Some options never take an argument. Some options always take an

15466

argument. Lots of people want an ``optional option arguments'' feature,

15467

meaning that some options will take an argument if they see it, and

15468

won't if they don't. This is somewhat controversial, because it makes

15469

parsing ambiguous: if -a and -b are both

15470

options, and -a takes an optional argument, how do we

15471

interpret -ab? optparse does not support optional

15472

option arguments.

15473

positional argument

15474

something leftover in the argument list after options have been

15475

parsed, i.e., after options and their arguments have been parsed and

15476

removed from the argument list.

15477

required option

15478

an option that must be supplied on the command-line. The phrase

15479

``required option'' is an oxymoron; the presence of ``required options''

15480

in a program is usually a sign of careless user interface design.

15481

optparse doesn't prevent you from implementing required

15482

options, but doesn't give you much help with it either. See ``Extending

15483

Examples'' (section~optparse-extending-examples) for two ways to

15484

implement required options with optparse.

15485

For example, consider this hypothetical command-line:

15486

prog -v --report /tmp/report.txt foo bar

15487

-v and report are both options. Assuming

15488

the report option takes one argument,

15489

/tmp/report.txt is an option argument. foo and bar

15490

are positional arguments.

15491

What are options for?

15492

Options are used to provide extra information to tune or customize the

15493

execution of a program. In case it wasn't clear, options should be

15494

optional. A program should be able to run just fine with no

15495

options whatsoever. (Pick a random program from the or GNU

15496

toolsets. Can it run without any options at all and still make sense?

15497

The only exceptions I can think of are find, tar,

15498

and dd---all of which are mutant oddballs that have been

15499

rightly criticized for their non-standard syntax and confusing

15500

interfaces.)

15501

Lots of people want their programs to have ``required options''.

15502

Think about it. If it's required, then it's not optional! If

15503

there is a piece of information that your program absolutely requires

15504

in order to run successfully, that's what positional arguments are

15505

for. (However, if you insist on adding ``required options'' to your

15506

programs, look in ``Extending Examples''

15507

(section~optparse-extending-examples) for two ways of

15508

implementing them with optparse.)

15509

Consider the humble cp utility, for copying files. It

15510

doesn't make much sense to try to copy files without supplying a

15511

destination and at least one source. Hence, cp fails if you

15512

run it with no arguments. However, it has a flexible, useful syntax

15513

that does not rely on options at all:

15514

$ cp SOURCE DEST

15515

$ cp SOURCE ... DEST-DIR

15516

You can get pretty far with just that. Most cp

15517

implementations provide a bunch of options to tweak exactly how the

15518

files are copied: you can preserve mode and modification time, avoid

15519

following symlinks, ask before clobbering existing files, etc. But

15520

none of this distracts from the core mission of cp, which is

15521

to copy one file to another, or N files to another directory.

15522

What are positional arguments for? In case it wasn't clear from the above example: positional arguments

15523

are for those pieces of information that your program absolutely,

15524

positively requires to run.

15525

A good user interface should have as few absolute requirements as

15526

possible. If your program requires 17 distinct pieces of information in

15527

order to run successfully, it doesn't much matter how you get that

15528

information from the user---most people will give up and walk away

15529

before they successfully run the program. This applies whether the user

15530

interface is a command-line, a configuration file, a GUI, or whatever:

15531

if you make that many demands on your users, most of them will just give

15532

up.

15533

In short, try to minimize the amount of information that users are

15534

absolutely required to supply---use sensible defaults whenever

15535

possible. Of course, you also want to make your programs reasonably

15536

flexible. That's what options are for. Again, it doesn't matter if

15537

they are entries in a config file, checkboxes in the ``Preferences''

15538

dialog of a GUI, or command-line options---the more options you

15539

implement, the more flexible your program is, and the more complicated

15540

its implementation becomes. It's quite easy to overwhelm users (and

15541

yourself!) with too much flexibility, so be careful there.

15542

</description>

15543

</group>

15544

15545

<description>While optparse is quite flexible and powerful, you don't have

15546

to jump through hoops or read reams of documentation to get it working

15547

in basic cases. This document aims to demonstrate some simple usage

15548

patterns that will get you started using optparse in your

15549

scripts.

15550

To parse a command line with optparse, you must create an

15551

OptionParser instance and populate it. Obviously, you'll have

15552

to import the OptionParser classes in any script that uses

15553

optparse:

15554

from optparse import OptionParser

15555

Early on in the main program, create a parser:

15556

parser = OptionParser()

15557

Then you can start populating the parser with options. Each option is

15558

really a set of synonymous option strings; most commonly, you'll have

15559

one short option string and one long option string ---

15560

e.g. -f and file:

15561

parser.add_option("-f", "--file", ...)

15562

The interesting stuff, of course, is what comes after the option

15563

strings. For now, we'll only cover four of the things you can put

15564

there: action, type, dest (destination), and

15565

help.

15566

The store action%

15567

The action tells optparse what to do when it sees one of the

15568

option strings for this option on the command-line. For example, the

15569

action store means: take the next argument (or the remainder of

15570

the current argument), ensure that it is of the correct type, and

15571

store it to your chosen destination.

15572

For example, let's fill in the ``...'' of that last option:

15573

parser.add_option("-f", "--file",

15574

action="store", type="string", dest="filename")

15575

Now let's make up a fake command-line and ask optparse to

15576

parse it:

15577

args = ["-f", "foo.txt"]

15578

(options, args) = parser.parse_args(args)

15579

(Note that if you don't pass an argument list to

15580

parse_args(), it automatically uses sys.argv[1:].)

15581

When optparse sees the -f, it consumes the next

15582

argument---foo.txt---and stores it in the filename

15583

attribute of a special object. That object is the first return value

15584

from parse_args(), so:

15585

print options.filename

15586

will print foo.txt.

15587

Other option types supported by optparse are int and

15588

float. Here's an option that expects an integer argument:

15589

parser.add_option("-n", type="int", dest="num")

15590

This example doesn't provide a long option, which is perfectly

15591

acceptable. It also doesn't specify the action---it defaults to

15592

``store''.

15593

Let's parse another fake command-line. This time, we'll jam the option

15594

argument right up against the option, since -n42 (one

15595

argument) is equivalent to -n 42 (two arguments).

15596

(options, args) = parser.parse_args(["-n42"])

15597

print options.num

15598

This prints 42.

15599

Trying out the ``float'' type is left as an exercise for the reader.

15600

If you don't specify a type, optparse assumes ``string''.

15601

Combined with the fact that the default action is ``store'', that

15602

means our first example can be a lot shorter:

15603

parser.add_option("-f", "--file", dest="filename")

15604

If you don't supply a destination, optparse figures out a

15605

sensible default from the option strings: if the first long option

15606

string is foo-bar, then the default destination is

15607

foo_bar. If there are no long option strings,

15608

optparse looks at the first short option: the default

15609

destination for -f is f.

15610

Adding types is fairly easy; please refer to

15611

section~optparse-adding-types, ``Adding new types.''

15612

Other store_* actions%

15613

Flag options---set a variable to true or false when a particular

15614

option is seen---are quite common. optparse supports them

15615

with two separate actions, ``store_true'' and ``store_false''. For

15616

example, you might have a verbose flag that is turned on with

15617

-v and off with -q:

15618

parser.add_option("-v", action="store_true", dest="verbose")

15619

parser.add_option("-q", action="store_false", dest="verbose")

15620

Here we have two different options with the same destination, which is

15621

perfectly OK. (It just means you have to be a bit careful when setting

15622

default values---see below.)

15623

When optparse sees -v on the command line, it sets

15624

options.verbose to True; when it sees -q, it

15625

sets options.verbose to False.

15626

Setting default values

15627

All of the above examples involve setting some variable (the

15628

``destination'') when certain command-line options are seen. What

15629

happens if those options are never seen? Since we didn't supply any

15630

defaults, they are all set to None. Sometimes, this is just fine (which

15631

is why it's the default), but sometimes, you want more control. To

15632

address that need, optparse lets you supply a default value for

15633

each destination, which is assigned before the command-line is parsed.

15634

First, consider the verbose/quiet example. If we want

15635

optparse to set verbose to True unless

15636

-q is seen, then we can do this:

15637

parser.add_option("-v", action="store_true", dest="verbose", default=True)

15638

parser.add_option("-q", action="store_false", dest="verbose")

15639

Oddly enough, this is exactly equivalent:

15640

parser.add_option("-v", action="store_true", dest="verbose")

15641

parser.add_option("-q", action="store_false", dest="verbose", default=True)

15642

Those are equivalent because you're supplying a default value for the

15643

option's destination, and these two options happen to have the same

15644

destination (the verbose variable).

15645

Consider this:

15646

parser.add_option("-v", action="store_true", dest="verbose", default=False)

15647

parser.add_option("-q", action="store_false", dest="verbose", default=True)

15648

Again, the default value for verbose will be True: the last

15649

default value supplied for any particular destination is the one that

15650

counts.

15651

Generating help

15652

The last feature that you will use in every script is

15653

optparse's ability to generate help messages. All you have

15654

to do is supply a help argument when you add an option. Let's

15655

create a new parser and populate it with user-friendly (documented)

15656

options:

15657

usage = "usage: %prog [options] arg1 arg2"

15658

parser = OptionParser(usage=usage)

15659

parser.add_option("-v", "--verbose",

15660

action="store_true", dest="verbose", default=True,

15661

help="make lots of noise [default]")

15662

parser.add_option("-q", "--quiet",

15663

action="store_false", dest="verbose", help="be vewwy quiet (I'm hunting wabbits)")

15664

parser.add_option("-f", "--file", dest="filename",

15665

metavar="FILE", help="write output to FILE"),

15666

parser.add_option("-m", "--mode",

15667

default="intermediate",

15668

help="interaction mode: one of 'novice', "

15669

"'intermediate' [default], 'expert'")

15670

If optparse encounters either -h or

15671

help on the command-line, or if you just call

15672

parser.print_help(), it prints the following to stdout:

15673

usage: <yourscript> [options] arg1 arg2

15674

options:

15675

-h, --help show this help message and exit

15676

-v, --verbose make lots of noise [default]

15677

-q, --quiet be vewwy quiet (I'm hunting wabbits)

15678

-fFILE, --file=FILE write output to FILE

15679

-mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'

15680

[default], 'expert'

15681

There's a lot going on here to help optparse generate the

15682

best possible help message:

15683

the script defines its own usage message:

15684

usage = "usage: %prog [options] arg1 arg2"

15685

optparse expands in the usage string to the name of the

15686

current script, i.e. os.path.basename(sys.argv[0]). The

15687

expanded string is then printed before the detailed option help.

15688

If you don't supply a usage string, optparse uses a bland but

15689

sensible default: "usage: [options]", which is fine if your

15690

script doesn't take any positional arguments.

15691

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.

15692

options that take a value indicate this fact in their

15693

automatically-generated help message, e.g. for the ``mode'' option:

15694

-mMODE, --mode=MODE

15695

Here, ``MODE'' is called the meta-variable: it stands for the argument

15696

that the user is expected to supply to

15697

-m/mode. By default, optparse

15698

converts the destination variable name to uppercase and uses that for

15699

the meta-variable. Sometimes, that's not what you want---for

15700

example, the filename option explicitly sets

15701

metavar="FILE", resulting in this automatically-generated

15702

option description:

15703

-fFILE, --file=FILE

15704

This is important for more than just saving space, though: the

15705

manually written help text uses the meta-variable ``FILE'', to clue

15706

the user in that there's a connection between the formal syntax

15707

``-fFILE'' and the informal semantic description ``write output to

15708

FILE''. This is a simple but effective way to make your help text a

15709

lot clearer and more useful for end users.

15710

When dealing with many options, it is convenient to group these

15711

options for better help output. An OptionParser can contain

15712

several option groups, each of which can contain several options.

15713

Continuing with the parser defined above, adding an

15714

OptionGroup to a parser is easy:

15715

group = OptionGroup(parser, "Dangerous Options",

15716

"Caution: use these options at your own risk. "

15717

"It is believed that some of them bite.")

15718

group.add_option("-g", action="store_true", help="Group option.")

15719

parser.add_option_group(group)

15720

This would result in the following help output:

15721

usage: [options] arg1 arg2

15722

options:

15723

-h, --help show this help message and exit

15724

-v, --verbose make lots of noise [default]

15725

-q, --quiet be vewwy quiet (I'm hunting wabbits)

15726

-fFILE, --file=FILE write output to FILE

15727

-mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'

15728

[default], 'expert'

15729

Dangerous Options:

15730

Caution: use of these options is at your own risk. It is believed that

15731

some of them bite.

15732

-g Group option.

15733

Print a version number

15734

Similar to the brief usage string, optparse can also print a

15735

version string for your program. You have to supply the string, as

15736

the version argument to OptionParser:

15737

parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")

15738

version can contain anything you like; is expanded

15739

in version just as with usage. When you supply it,

15740

optparse automatically adds a version option

15741

to your parser. If it encounters this option on the command line, it

15742

expands your version string (by replacing ), prints

15743

it to stdout, and exits.

15744

For example, if your script is called /usr/bin/foo, a user might do:

15745

$ /usr/bin/foo --version

15746

foo 1.0

15747

% $ (avoid confusing emacs)

15748

Error-handling

15749

The one thing you need to know for basic usage is how

15750

optparse behaves when it encounters an error on the

15751

command-line---e.g. -n 4x where -n is an

15752

integer-valued option. In this case, optparse prints your

15753

usage message to stderr, followed by a useful and human-readable error

15754

message. Then it terminates (calls sys.exit()) with a

15755

non-zero exit status.

15756

If you don't like this, subclass OptionParser and override the

15757

error() method. See section~optparse-extending,

15758

``Extending optparse.''

15759

Putting it all together

15760

Here's what optparse-based scripts typically look like:

15761

from optparse import OptionParser

15762

[...]

15763

def main():

15764

usage = "usage: [-f] [-v] [-q] firstarg secondarg"

15765

parser = OptionParser(usage)

15766

parser.add_option("-f", "--file", type="string", dest="filename",

15767

help="read data from FILENAME")

15768

parser.add_option("-v", "--verbose",

15769

action="store_true", dest="verbose")

15770

parser.add_option("-q", "--quiet",

15771

action="store_false", dest="verbose")

15772

(options, args) = parser.parse_args()

15773

if len(args) != 1:

15774

parser.error("incorrect number of arguments")

15775

if options.verbose:

15776

print "reading ..." % options.filename

15777

[... go to work ...]

15778

if __name__ == "__main__":

15779

main()

15780

</description>

15781

</group>

15782

15783

<description>Creating and populating the

15784

parser

15785

There are several ways to populate the parser with options. One way

15786

is to pass a list of Options to the OptionParser

15787

constructor:

15788

from optparse import OptionParser, make_option

15789

[...]

15790

parser = OptionParser(option_list=[

15791

make_option("-f", "--filename",

15792

action="store", type="string", dest="filename"),

15793

make_option("-q", "--quiet",

15794

action="store_false", dest="verbose")])

15795

(make_option() is a factory function for generating

15796

Option objects.)

15797

For long option lists, it may be more convenient/readable to create the

15798

list separately:

15799

option_list = [make_option("-f", "--filename",

15800

action="store", type="string", dest="filename"),

15801

[... more options ...]

15802

make_option("-q", "--quiet",

15803

action="store_false", dest="verbose")]

15804

parser = OptionParser(option_list=option_list)

15805

Or, you can use the add_option() method of

15806

OptionParser to add options one-at-a-time:

15807

parser = OptionParser()

15808

parser.add_option("-f", "--filename",

15809

action="store", type="string", dest="filename")

15810

parser.add_option("-q", "--quiet",

15811

action="store_false", dest="verbose")

15812

This method makes it easier to track down exceptions raised by the

15813

Option constructor, which are common because of the complicated

15814

interdependencies among the various keyword arguments. (If you get it

15815

wrong, optparse raises OptionError.)

15816

add_option() can be called in one of two ways:

15817

pass it an Option instance (as returned by make_option())

15818

pass it any combination of positional and keyword arguments that

15819

are acceptable to make_option() (i.e., to the Option

15820

constructor), and it will create the Option instance for you

15821

(shown above).

15822

Defining options

15823

Each Option instance represents a set of synonymous

15824

command-line options, i.e. options that have the same meaning and

15825

effect, but different spellings. You can specify any number of short

15826

or long option strings, but you must specify at least one option

15827

string.

15828

To define an option with only a short option string:

15829

make_option("-f", ...)

15830

And to define an option with only a long option string:

15831

make_option("--foo", ...)

15832

The ``...'' represents a set of keyword arguments that define attributes

15833

of the Option object. The rules governing which keyword args

15834

you must supply for a given Option are fairly complicated, but

15835

you always have to supply some. If you get it wrong,

15836

optparse raises an OptionError exception explaining

15837

your mistake.

15838

The most important attribute of an option is its action, i.e. what to do

15839

when we encounter this option on the command-line. The possible actions

15840

are:

15841

{l|l}{code}{Action}{Meaning}

15842

store{store this option's argument (default)}

15843

store_const{store a constant value}

15844

store_true{store a true value}

15845

store_false{store a false value}

15846

append{append this option's argument to a list}

15847

count{increment a counter by one}

15848

callback{call a specified function}

15849

help{print a usage message including all options and the

15850

documentation for them} (If you don't supply an action, the default is ``store''. For this

15851

action, you may also supply type and dest keywords; see

15852

below.)

15853

As you can see, most actions involve storing or updating a value

15854

somewhere. optparse always creates a particular object (an

15855

instance of the Values class) specifically for this

15856

purpose. Option arguments (and various other values) are stored as

15857

attributes of this object, according to the dest (destination)

15858

argument to make_option()/add_option().

15859

For example, when you call:

15860

parser.parse_args()

15861

one of the first things optparse does is create a

15862

values object:

15863

values = Values()

15864

If one of the options in this parser is defined with:

15865

make_option("-f", "--file", action="store", type="string", dest="filename")

15866

and the command-line being parsed includes any of the following:

15867

-ffoo

15868

-f foo

15869

--file=foo

15870

--file foo

15871

then optparse, on seeing the -f or

15872

file option, will do the equivalent of this:

15873

values.filename = "foo"

15874

Clearly, the type and dest arguments are almost

15875

as important as action. action is the only attribute that

15876

is meaningful for all options, though, so it is the most

15877

important.

15878

Option actions

15879

The various option actions all have slightly different requirements

15880

and effects. Except for the ``help'' action, you must supply at least

15881

one other keyword argument when creating the Option; the exact

15882

requirements for each action are listed here.

15883

store [relevant: type, dest, nargs, choices]

15884

The option must be followed by an argument, which is converted to a

15885

value according to type and stored in dest. If

15886

nargs > 1, multiple arguments will be consumed from the command

15887

line; all will be converted according to type and stored to

15888

dest as a tuple. See section~optparse-option-types,

15889

``Option types,'' below.

15890

If choices (a sequence of strings) is supplied, the type

15891

defaults to ``choice''.

15892

If type is not supplied, it defaults to ``string''.

15893

If dest is not supplied, optparse derives a

15894

destination from the first long option strings (e.g.,

15895

foo-bar becomes foo_bar). If there are no long

15896

option strings, optparse derives a destination from the first

15897

short option string (e.g., -f becomes f).

15898

Example:

15899

make_option("-f")

15900

make_option("-p", type="float", nargs=3, dest="point")

15901

Given the following command line:

15902

-f foo.txt -p 1 -3.5 4 -fbar.txt

15903

optparse will set:

15904

values.f = "bar.txt"

15905

values.point = (1.0, -3.5, 4.0)

15906

(Actually, values.f will be set twice, but only the second

15907

time is visible in the end.)

15908

store_const [required: const, dest]

15909

The const value supplied to the Option constructor is

15910

stored in dest.

15911

Example:

15912

make_option("-q", "--quiet",

15913

action="store_const", const=0, dest="verbose"),

15914

make_option("-v", "--verbose",

15915

action="store_const", const=1, dest="verbose"),

15916

make_option("--noisy",

15917

action="store_const", const=2, dest="verbose"),

15918

If noisy is seen, optparse will set:

15919

values.verbose = 2

15920

store_true [required: dest]

15921

A special case of ``store_const'' that stores True to dest.

15922

store_false [required: dest]

15923

Like ``store_true'', but stores False

15924

Example:

15925

make_option(None, "--clobber", action="store_true", dest="clobber")

15926

make_option(None, "--no-clobber", action="store_false", dest="clobber")

15927

append [relevant: type, dest, nargs, choices]

15928

The option must be followed by an argument, which is appended to the

15929

list in dest. If no default value for dest is supplied

15930

(i.e. the default is None), an empty list is automatically created when

15931

optparse first encounters this option on the command-line.

15932

If nargs > 1, multiple arguments are consumed, and a tuple of

15933

length nargs is appended to dest.

15934

The defaults for type and dest are the same as for the

15935

``store'' action.

15936

Example:

15937

make_option("-t", "--tracks", action="append", type="int")

15938

If -t3 is seen on the command-line, optparse does the equivalent of:

15939

values.tracks = []

15940

values.tracks.append(int("3"))

15941

If, a little later on, tracks=4 is seen, it does:

15942

values.tracks.append(int("4"))

15943

See ``Error handling'' (section~optparse-error-handling) for

15944

information on how optparse deals with something like

15945

tracks=x.

15946

count [required: dest]

15947

Increment the integer stored at dest. dest is set to zero

15948

before being incremented the first time (unless you supply a default

15949

value).

15950

Example:

15951

make_option("-v", action="count", dest="verbosity")

15952

The first time -v is seen on the command line,

15953

optparse does the equivalent of:

15954

values.verbosity = 0

15955

values.verbosity += 1

15956

Every subsequent occurrence of -v results in:

15957

values.verbosity += 1

15958

callback [required: callback;

15959

relevant: type, nargs, callback_args,

15960

callback_kwargs]

15961

Call the function specified by callback. The signature of

15962

this function should be:

15963

func(option : Option,

15964

opt : string,

15965

value : any,

15966

parser : OptionParser,

15967

*args, **kwargs)

15968

Callback options are covered in detail in

15969

section~optparse-callback-options, ``Callback Options.''

15970

help [required: none]

15971

Prints a complete help message for all the options in the current

15972

option parser. The help message is constructed from the usage

15973

string passed to OptionParser's constructor and the help

15974

string passed to every option.

15975

If no help string is supplied for an option, it will still be

15976

listed in the help message. To omit an option entirely, use the

15977

special value optparse.SUPPRESS_HELP.

15978

Example:

15979

from optparse import Option, OptionParser, SUPPRESS_HELP

15980

usage = "usage: %prog [options]"

15981

parser = OptionParser(usage, option_list=[

15982

make_option("-h", "--help", action="help"),

15983

make_option("-v", action="store_true", dest="verbose",

15984

help="Be moderately verbose")

15985

make_option("--file", dest="filename",

15986

help="Input file to read data from"),

15987

make_option("--secret", help=SUPPRESS_HELP)

15988

])

15989

If optparse sees either -h or

15990

help on the command line, it will print something

15991

like the following help message to stdout:

15992

usage: <yourscript> [options]

15993

options:

15994

-h, --help Show this help message and exit

15995

-v Be moderately verbose

15996

--file=FILENAME Input file to read data from

15997

After printing the help message, optparse terminates your process

15998

with sys.exit(0).

15999

version [required: none]

16000

Prints the version number supplied to the OptionParser to

16001

stdout and exits. The version number is actually formatted and

16002

printed by the print_version() method of

16003

OptionParser. Generally only relevant if the version

16004

argument is supplied to the OptionParser constructor.

16005

Option types

16006

optparse supports six option types out of the box: string,

16007

int, long, choice, float and complex.

16008

(Of these, string, int, float, and choice are the most commonly used

16009

---long and complex are there mainly for completeness.) It's easy to

16010

add new option types by subclassing the Option class; see

16011

section~optparse-extending, ``Extending optparse.''

16012

Arguments to string options are not checked or converted in any way:

16013

the text on the command line is stored in the destination (or passed

16014

to the callback) as-is.

16015

Integer arguments are passed to int() to convert them to

16016

Python integers. If int() fails, so will

16017

optparse, although with a more useful error message.

16018

Internally, optparse raises OptionValueError in

16019

optparse.check_builtin(); at a higher level (in

16020

OptionParser), optparse catches this exception and

16021

terminates your program with a useful error message.

16022

Likewise, float arguments are passed to float() for

16023

conversion, long arguments to long(), and complex arguments

16024

to complex(). Apart from that, they are handled

16025

identically to integer arguments.

16026

Choice options are a subtype of string options. A master list or

16027

tuple of choices (strings) must be passed to the option constructor

16028

(make_option() or OptionParser.add_option()) as

16029

the choices keyword argument. Choice option arguments are

16030

compared against this master list in

16031

optparse.check_choice(), and OptionValueError

16032

is raised if an unknown string is given.

16033

Querying and manipulating your option parser

16034

Sometimes, it's useful to poke around your option parser and see what's

16035

there. OptionParser provides a couple of methods to help you out:

16036

</description>

16037

16038

<description>Given an option string such as -q or

16039

verbose, returns true if the OptionParser

16040

has an option with that option string.</description>

16041

<param name="opt_stropt_str" optional="0">opt_stropt_str</param>

16042

<insert>has_option(opt_stropt_str)</insert><dialog title="Insert has_option">has_option(%0)</dialog><info title="Info window"></info></function>

16043

16044

16045

<description>Returns the Option instance that implements the option

16046

string you supplied, or None if no options implement it.</description>

16047

<param name="opt_stropt_str" optional="0">opt_stropt_str</param>

16048

<insert>get_option(opt_stropt_str)</insert><dialog title="Insert get_option">get_option(%0)</dialog><info title="Info window"></info></function>

16049

16050

16051

<description>If the OptionParser has an option corresponding to

16052

opt_str, that option is removed. If that option provided

16053

any other option strings, all of those option strings become

16054

invalid.

16055

If opt_str does not occur in any option belonging to this

16056

OptionParser, raises ValueError.</description>

16057

<param name="opt_stropt_str" optional="0">opt_stropt_str</param>

16058

<insert>remove_option(opt_stropt_str)</insert><dialog title="Insert remove_option">remove_option(%0)</dialog><info title="Info window"></info></function>

16059

16060

</group>

16061

16062

<description>If optparse's built-in actions and types just don't fit the

16063

bill for you, but it's not worth extending optparse to define

16064

your own actions or types, you'll probably need to define a callback

16065

option. Defining callback options is quite easy; the tricky part is

16066

writing a good callback (the function that is called when

16067

optparse encounters the option on the command line).

16068

Defining a callback option

16069

As always, you can define a callback option either by directly

16070

instantiating the Option class, or by using the

16071

add_option() method of your OptionParser object. The

16072

only option attribute you must specify is callback, the function

16073

to call:

16074

parser.add_option("-c", callback=my_callback)

16075

Note that you supply a function object here---so you must have

16076

already defined a function my_callback() when you define

16077

the callback option. In this simple case, optparse knows

16078

nothing about the arguments the -c option expects to

16079

take. Usually, this means that the option doesn't take any arguments

16080

-- the mere presence of -c on the command-line is all it

16081

needs to know. In some circumstances, though, you might want your

16082

callback to consume an arbitrary number of command-line arguments.

16083

This is where writing callbacks gets tricky; it's covered later in

16084

this document.

16085

There are several other option attributes that you can supply when you

16086

define an option attribute:

16087

type

16088

has its usual meaning: as with the ``store'' or ``append'' actions, it

16089

instructs optparse to consume one argument that must be

16090

convertible to type. Rather than storing the value(s) anywhere,

16091

though, optparse converts it to type and passes it to

16092

your callback function.

16093

nargs

16094

also has its usual meaning: if it is supplied and nargs > 1,

16095

optparse will consume nargs arguments, each of which

16096

must be convertible to type. It then passes a tuple of

16097

converted values to your callback.

16098

callback_args

16099

a tuple of extra positional arguments to pass to the callback.

16100

callback_kwargs

16101

a dictionary of extra keyword arguments to pass to the callback.

16102

How callbacks are called

16103

All callbacks are called as follows:

16104

func(option, opt, value, parser, *args, **kwargs)

16105

where

16106

option

16107

is the Option instance that's calling the callback.

16108

opt

16109

is the option string seen on the command-line that's triggering the

16110

callback. (If an abbreviated long option was used, opt will be

16111

the full, canonical option string---for example, if the user puts

16112

foo on the command-line as an abbreviation for

16113

foobar, then opt will be

16114

foobar.)

16115

value

16116

is the argument to this option seen on the command-line.

16117

optparse will only expect an argument if type is

16118

set; the type of value will be the type implied by the

16119

option's type (see~optparse-option-types, ``Option types''). If

16120

type for this option is None (no argument expected), then

16121

value will be None. If nargs > 1, value will

16122

be a tuple of values of the appropriate type.

16123

parser

16124

is the OptionParser instance driving the whole thing, mainly

16125

useful because you can access some other interesting data through it,

16126

as instance attributes:

16127

parser.rargs

16128

the current remaining argument list, i.e. with opt (and

16129

value, if any) removed, and only the arguments following

16130

them still there. Feel free to modify parser.rargs,

16131

e.g. by consuming more arguments.

16132

parser.largs

16133

the current set of leftover arguments, i.e. arguments that have been

16134

processed but have not been consumed as options (or arguments to

16135

options). Feel free to modify parser.largs e.g. by adding

16136

more arguments to it.

16137

parser.values

16138

the object where option values are by default stored. This is useful

16139

because it lets callbacks use the same mechanism as the rest of

16140

optparse for storing option values; you don't need to mess

16141

around with globals or closures. You can also access the value(s) of

16142

any options already encountered on the command-line.

16143

args

16144

is a tuple of arbitrary positional arguments supplied via the

16145

callback_args option attribute.

16146

kwargs

16147

is a dictionary of arbitrary keyword arguments supplied via

16148

callback_kwargs.

16149

Since args and kwargs are optional (they are only passed

16150

if you supply callback_args and/or callback_kwargs when

16151

you define your callback option), the minimal callback function is:

16152

def my_callback (option, opt, value, parser):

16153

pass

16154

Error handling

16155

The callback function should raise OptionValueError if

16156

there are any problems with the option or its

16157

argument(s). optparse catches this and terminates the

16158

program, printing the error message you supply to stderr. Your

16159

message should be clear, concise, accurate, and mention the option at

16160

fault. Otherwise, the user will have a hard time figuring out what he

16161

did wrong.

16162

Examples

16163

Here's an example of a callback option that takes no arguments, and

16164

simply records that the option was seen:

16165

def record_foo_seen (option, opt, value, parser):

16166

parser.saw_foo = 1

16167

parser.add_option("--foo", action="callback", callback=record_foo_seen)

16168

Of course, you could do that with the ``store_true'' action. Here's a

16169

slightly more interesting example: record the fact that

16170

-a is seen, but blow up if it comes after -b

16171

in the command-line.

16172

def check_order (option, opt, value, parser):

16173

if parser.values.b:

16174

raise OptionValueError("can't use -a after -b")

16175

parser.values.a = 1

16176

...

16177

parser.add_option("-a", action="callback", callback=check_order)

16178

parser.add_option("-b", action="store_true", dest="b")

16179

If you want to reuse this callback for several similar options (set a

16180

flag, but blow up if -b has already been seen), it needs

16181

a bit of work: the error message and the flag that it sets must be

16182

generalized.

16183

def check_order (option, opt, value, parser):

16184

if parser.values.b:

16185

raise OptionValueError("can't use %s after -b" % opt)

16186

setattr(parser.values, option.dest, 1)

16187

...

16188

parser.add_option("-a", action="callback", callback=check_order, dest='a')

16189

parser.add_option("-b", action="store_true", dest="b")

16190

parser.add_option("-c", action="callback", callback=check_order, dest='c')

16191

Of course, you could put any condition in there---you're not limited

16192

to checking the values of already-defined options. For example, if

16193

you have options that should not be called when the moon is full, all

16194

you have to do is this:

16195

def check_moon (option, opt, value, parser):

16196

if is_full_moon():

16197

raise OptionValueError("%s option invalid when moon full" % opt)

16198

setattr(parser.values, option.dest, 1)

16199

...

16200

parser.add_option("--foo",

16201

action="callback", callback=check_moon, dest="foo")

16202

(The definition of is_full_moon() is left as an exercise for the

16203

reader.)

16204

Fixed arguments

16205

Things get slightly more interesting when you define callback options

16206

that take a fixed number of arguments. Specifying that a callback

16207

option takes arguments is similar to defining a ``store'' or

16208

``append'' option: if you define type, then the option takes one

16209

argument that must be convertible to that type; if you further define

16210

nargs, then the option takes that many arguments.

16211

Here's an example that just emulates the standard ``store'' action:

16212

def store_value (option, opt, value, parser):

16213

setattr(parser.values, option.dest, value)

16214

...

16215

parser.add_option("--foo",

16216

action="callback", callback=store_value,

16217

type="int", nargs=3, dest="foo")

16218

Note that optparse takes care of consuming 3 arguments and

16219

converting them to integers for you; all you have to do is store them.

16220

(Or whatever: obviously you don't need a callback for this example.

16221

Use your imagination!)

16222

Variable arguments

16223

Things get hairy when you want an option to take a variable number of

16224

arguments. For this case, you have to write a callback;

16225

optparse doesn't provide any built-in capabilities for it.

16226

You have to deal with the full-blown syntax for conventional command-line parsing. (Previously, optparse took care of

16227

this for you, but I got it wrong. It was fixed at the cost of making

16228

this kind of callback more complex.) In particular, callbacks have to

16229

worry about bare and - arguments; the

16230

convention is:

16231

bare , if not the argument to some option,

16232

causes command-line processing to halt and the itself is lost.

16233

bare - similarly causes command-line processing to

16234

halt, but the - itself is kept.

16235

either or - can be option

16236

arguments.

16237

If you want an option that takes a variable number of arguments, there

16238

are several subtle, tricky issues to worry about. The exact

16239

implementation you choose will be based on which trade-offs you're

16240

willing to make for your application (which is why optparse

16241

doesn't support this sort of thing directly).

16242

Nevertheless, here's a stab at a callback for an option with variable

16243

arguments:

16244

def varargs (option, opt, value, parser):

16245

assert value is None

16246

done = 0

16247

value = []

16248

rargs = parser.rargs

16249

while rargs:

16250

arg = rargs[0]

16251

# Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",

16252

# etc. Note that this also stops on "-3" or "-3.0", so if

16253

# your option takes numeric values, you will need to handle

16254

# this.

16255

if ((arg[:2] == "--" and len(arg) > 2) or

16256

(arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):

16257

break

16258

else:

16259

value.append(arg)

16260

del rargs[0]

16261

setattr(parser.values, option.dest, value)

16262

...

16263

parser.add_option("-c", "--callback",

16264

action="callback", callback=varargs)

16265

The main weakness with this particular implementation is that negative

16266

numbers in the arguments following -c will be interpreted

16267

as further options, rather than as arguments to -c.

16268

Fixing this is left as an exercise for the reader.

16269

</description>

16270

</group>

16271

16272

</group>

16273

</group>

16274

16275

<description>Generate temporary files and directories.

16276

This module generates temporary files and directories. It works on

16277

all supported platforms.

16278

In version 2.3 of Python, this module was overhauled for enhanced

16279

security. It now provides three new functions,

16280

NamedTemporaryFile(), mkstemp(), and

16281

mkdtemp(), which should eliminate all remaining need to use

16282

the insecure mktemp() function. Temporary file names created

16283

by this module no longer contain the process ID; instead a string of

16284

six random characters is used.

16285

Also, all the user-callable functions now take additional arguments

16286

which allow direct control over the location and name of temporary

16287

files. It is no longer necessary to use the global tempdir and

16288

template variables. To maintain backward compatibility, the

16289

argument order is somewhat odd; it is recommended to use keyword

16290

arguments for clarity.

16291

The module defines the following user-callable functions:

16292

</description>

16293

16294

<description>Return a file (or file-like) object that can be used as a temporary

16295

storage area. The file is created using mkstemp. It will

16296

be destroyed as soon as it is closed (including an implicit close when

16297

the object is garbage collected). Under , the directory entry

16298

for the file is removed immediately after the file is created. Other

16299

platforms do not support this; your code should not rely on a

16300

temporary file created using this function having or not having a

16301

visible name in the file system.

16302

The mode parameter defaults to 'w+b' so that the file

16303

created can be read and written without being closed. Binary mode is

16304

used so that it behaves consistently on all platforms without regard

16305

for the data that is stored. bufsize defaults to -1,

16306

meaning that the operating system default is used.

16307

The dir, prefix and suffix parameters are passed to

16308

mkstemp().</description>

16309

<param name="mode" optional="0" default="'w+b'">mode</param><param name="bufsize" optional="1" default="-1">bufsize</param><param name="suffix" optional="1">suffix</param><param name="prefix" optional="1">prefix</param><param name="dir" optional="1">dir</param>

16310

<insert>TemporaryFile(mode, [bufsize=-1], [suffix], [prefix], [dir])</insert><dialog title="Insert TemporaryFile">TemporaryFile(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

16311

16312

16313

<description>This function operates exactly as TemporaryFile() does,

16314

except that the file is guaranteed to have a visible name in the file

16315

system (on , the directory entry is not unlinked). That name can

16316

be retrieved from the name member of the file object. Whether

16317

the name can be used to open the file a second time, while the

16318

named temporary file is still open, varies across platforms (it can

16319

be so used on ; it cannot on Windows NT or later).

16320

New in version 2.3</description>

16321

<param name="mode" optional="0" default="'w+b'">mode</param><param name="bufsize" optional="1" default="-1">bufsize</param><param name="suffix" optional="1">suffix</param><param name="prefix" optional="1">prefix</param><param name="dir" optional="1">dir</param>

16322

<insert>NamedTemporaryFile(mode, [bufsize=-1], [suffix], [prefix], [dir])</insert><dialog title="Insert NamedTemporaryFile">NamedTemporaryFile(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

16323

16324

16325

<description>Creates a temporary file in the most secure manner possible. There

16326

are no race conditions in the file's creation, assuming that the

16327

platform properly implements the O_EXCL flag for

16328

os.open(). The file is readable and writable only by the

16329

creating user ID. If the platform uses permission bits to indicate

16330

whether a file is executable, the file is executable by no one. The

16331

file descriptor is not inherited by child processes.

16332

Unlike TemporaryFile(), the user of mkstemp() is

16333

responsible for deleting the temporary file when done with it.

16334

If suffix is specified, the file name will end with that suffix,

16335

otherwise there will be no suffix. mkstemp() does not put a

16336

dot between the file name and the suffix; if you need one, put it at

16337

the beginning of suffix.

16338

If prefix is specified, the file name will begin with that

16339

prefix; otherwise, a default prefix is used.

16340

If dir is specified, the file will be created in that directory;

16341

otherwise, a default directory is used.

16342

If text is specified, it indicates whether to open the file in

16343

binary mode (the default) or text mode. On some platforms, this makes

16344

no difference.

16345

mkstemp() returns a tuple containing an OS-level handle to

16346

an open file (as would be returned by os.open()) and the

16347

absolute pathname of that file, in that order.

16348

New in version 2.3</description>

16349

<param name="suffix" optional="0">suffix</param><param name="prefix" optional="1">prefix</param><param name="dir" optional="1">dir</param><param name="text" optional="1">text</param>

16350

<insert>mkstemp(suffix, [prefix], [dir], [text])</insert><dialog title="Insert mkstemp">mkstemp(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

16351

16352

16353

<description>Creates a temporary directory in the most secure manner possible.

16354

There are no race conditions in the directory's creation. The

16355

directory is readable, writable, and searchable only by the

16356

creating user ID.

16357

The user of mkdtemp() is responsible for deleting the

16358

temporary directory and its contents when done with it.

16359

The prefix, suffix, and dir arguments are the same

16360

as for mkstemp().

16361

mkdtemp() returns the absolute pathname of the new directory.

16362

New in version 2.3</description>

16363

<param name="suffix" optional="0">suffix</param><param name="prefix" optional="1">prefix</param><param name="dir" optional="1">dir</param>

16364

<insert>mkdtemp(suffix, [prefix], [dir])</insert><dialog title="Insert mkdtemp">mkdtemp(%0, %1, %2)</dialog><info title="Info window"></info></function>

16365

16366

16367

<description>2.3{Use mkstemp() instead.}

16368

Return an absolute pathname of a file that did not exist at the time

16369

the call is made. The prefix, suffix, and dir

16370

arguments are the same as for mkstemp().

16371

Use of this function may introduce a security hole in your

16372

program. By the time you get around to doing anything with the file

16373

name it returns, someone else may have beaten you to the punch.</description>

16374

<param name="suffix" optional="0">suffix</param><param name="prefix" optional="1">prefix</param><param name="dir" optional="1">dir</param>

16375

<insert>mktemp(suffix, [prefix], [dir])</insert><dialog title="Insert mktemp">mktemp(%0, %1, %2)</dialog><info title="Info window"></info></function>

16376

16377

16378

<description>Return the directory currently selected to create temporary files in.

16379

If tempdir is not None, this simply returns its contents;

16380

otherwise, the search described above is performed, and the result

16381

returned.</description>

16382

16383

<insert>gettempdir()</insert><dialog title="Insert gettempdir">gettempdir()</dialog><info title="Info window"></info></function>

16384

16385

16386

<description>Return the filename prefix used to create temporary files. This does

16387

not contain the directory component. Using this function is preferred

16388

over reading the template variable directly.

16389

New in version 1.5.2</description>

16390

16391

<insert>gettempprefix()</insert><dialog title="Insert gettempprefix">gettempprefix()</dialog><info title="Info window"></info></function>

16392

16393

</group>

16394

16395

</group>

16396

16397

<description>style pathname pattern expansion.

16398

The glob module finds all the pathnames matching a specified

16399

pattern according to the rules used by the shell. No tilde

16400

expansion is done, but *, ?, and character ranges

16401

expressed with [] will be correctly matched. This is done by

16402

using the os.listdir() and fnmatch.fnmatch()

16403

functions in concert, and not by actually invoking a subshell. (For

16404

tilde and shell variable expansion, use os.path.expanduser()

16405

and os.path.expandvars().)

16406

</description>

16407

16408

<description>Returns a possibly-empty list of path names that match pathname,

16409

which must be a string containing a path specification.

16410

pathname can be either absolute (like

16411

/usr/src/Python-1.5/Makefile) or relative (like

16412

../../Tools/*/*.gif), and can contain shell-style wildcards.</description>

16413

<param name="pathnamepathname" optional="0">pathnamepathname</param>

16414

<insert>glob(pathnamepathname)</insert><dialog title="Insert glob">glob(%0)</dialog><info title="Info window"></info></function>

16415

16416

</group>

16417

16418

<description>style filename pattern matching.

16419

</description>

16420

16421

<description>Test whether the filename string matches the pattern

16422

string, returning true or false. If the operating system is

16423

case-insensitive, then both parameters will be normalized to all

16424

lower- or upper-case before the comparison is performed. If you

16425

require a case-sensitive comparison regardless of whether that's

16426

standard for your operating system, use fnmatchcase()

16427

instead.</description>

16428

<param name="filename" optional="0">filename</param><param name="pattern pattern" optional="0">pattern pattern</param>

16429

<insert>fnmatch(filename, pattern pattern)</insert><dialog title="Insert fnmatch">fnmatch(%0, %1)</dialog><info title="Info window"></info></function>

16430

16431

16432

<description>Test whether filename matches pattern, returning true or

16433

false; the comparison is case-sensitive.</description>

16434

<param name="filename" optional="0">filename</param><param name="pattern pattern" optional="0">pattern pattern</param>

16435

<insert>fnmatchcase(filename, pattern pattern)</insert><dialog title="Insert fnmatchcase">fnmatchcase(%0, %1)</dialog><info title="Info window"></info></function>

16436

16437

16438

<description>Return the subset of the list of names that match pattern.

16439

It is the same as [n for n in names if fnmatch(n, pattern)], but

16440

implemented more efficiently.

16441

New in version 2.2</description>

16442

<param name="names" optional="0">names</param><param name="pattern pattern" optional="0">pattern pattern</param>

16443

<insert>filter(names, pattern pattern)</insert><dialog title="Insert filter">filter(%0, %1)</dialog><info title="Info window"></info></function>

16444

16445

</group>

16446

16447

<description>High-level file operations, including copying.

16448

% partly based on the docstrings

16449

The shutil module offers a number of high-level operations on

16450

files and collections of files. In particular, functions are provided which support file copying and removal.

16451

</description>

16452

16453

<description>Copy the contents of the file named src to a file named

16454

dst. If dst exists, it will be replaced, otherwise it

16455

will be created. Special files such as character or block devices

16456

and pipes cannot not be copied with this function. src and

16457

dst are path names given as strings.</description>

16458

16459

<insert>copyfile(src, dst dst)</insert><dialog title="Insert copyfile">copyfile(%0, %1)</dialog><info title="Info window"></info></function>

16460

16461

16462

<description>Copy the contents of the file-like object fsrc to the

16463

file-like object fdst. The integer length, if given,

16464

is the buffer size. In particular, a negative length value

16465

means to copy the data without looping over the source data in

16466

chunks; by default the data is read in chunks to avoid uncontrolled

16467

memory consumption.</description>

16468

<param name="fsrc" optional="0">fsrc</param><param name="fdst" optional="0">fdst</param><param name="length" optional="1">length</param>

16469

<insert>copyfileobj(fsrc, fdst, [length])</insert><dialog title="Insert copyfileobj">copyfileobj(%0, %1, %2)</dialog><info title="Info window"></info></function>

16470

16471

16472

<description>Copy the permission bits from src to dst. The file

16473

contents, owner, and group are unaffected. src and dst

16474

are path names given as strings.</description>

16475

16476

<insert>copymode(src, dst dst)</insert><dialog title="Insert copymode">copymode(%0, %1)</dialog><info title="Info window"></info></function>

16477

16478

16479

<description>Copy the permission bits, last access time, and last modification

16480

time from src to dst. The file contents, owner, and

16481

group are unaffected. src and dst are path names given

16482

as strings.</description>

16483

16484

<insert>copystat(src, dst dst)</insert><dialog title="Insert copystat">copystat(%0, %1)</dialog><info title="Info window"></info></function>

16485

16486

16487

<description>Copy the file src to the file or directory dst. If

16488

dst is a directory, a file with the same basename as src is created (or overwritten) in the directory specified. Permission

16489

bits are copied. src and dst are path names given as

16490

strings.</description>

16491

16492

16493

16494

16495

<description>Similar to copy(), but last access time and last

16496

modification time are copied as well. This is similar to the

16497

command cp -p.</description>

16498

16499

16500

16501

16502

<description>Recursively copy an entire directory tree rooted at src. The

16503

destination directory, named by dst, must not already exist;

16504

it will be created. Individual files are copied using

16505

copy2(). If symlinks is true, symbolic links in

16506

the source tree are represented as symbolic links in the new tree;

16507

if false or omitted, the contents of the linked files are copied to

16508

the new tree. If exception(s) occur, an Error is raised

16509

with a list of reasons.

16510

The source code for this should be considered an example rather than a tool.

16511

Changed in version 2.3: Error is raised if any exceptions occur during copying,

16512

rather than printing a message</description>

16513

<param name="src" optional="0">src</param><param name="dst" optional="0">dst</param><param name="symlinks" optional="1">symlinks</param>

16514

<insert>copytree(src, dst, [symlinks])</insert><dialog title="Insert copytree">copytree(%0, %1, %2)</dialog><info title="Info window"></info></function>

16515

16516

16517

<description>Delete an entire directory tree.</description>

16518

<param name="path" optional="0">path</param><param name="ignore_errors" optional="1">ignore_errors</param><param name="onerror" optional="1">onerror</param>

16519

<insert>rmtree(path, [ignore_errors], [onerror])</insert><dialog title="Insert rmtree">rmtree(%0, %1, %2)</dialog><info title="Info window"></info></function>

16520

16521

16522

<description>Recursively move a file or directory to another location.

16523

If the destination is on our current filesystem, then simply use

16524

rename. Otherwise, copy src to the dst and then remove src.

16525

New in version 2.3</description>

16526

16527

16528

16529

16530

</group>

16531

</group>

16532

16533

<description>Internationalization services.

16534

The locale module opens access to the locale

16535

database and functionality. The locale mechanism allows

16536

programmers to deal with certain cultural issues in an application,

16537

without requiring the programmer to know all the specifics of each

16538

country where the software is executed.

16539

The locale module is implemented on top of the

16540

_locale_locale module, which in turn uses an

16541

ANSI C locale implementation if available.

16542

The locale module defines the following exception and

16543

functions:

16544

{Error}

16545

Exception raised when setlocale() fails.

16546

</description>

16547

16548

<description>If locale is specified, it may be a string, a tuple of the

16549

form (language code, encoding), or None.

16550

If it is a tuple, it is converted to a string using the locale

16551

aliasing engine. If locale is given and not None,

16552

setlocale() modifies the locale setting for the

16553

category. The available categories are listed in the data

16554

description below. The value is the name of a locale. An empty

16555

string specifies the user's default settings. If the modification of

16556

the locale fails, the exception Error is raised. If

16557

successful, the new locale setting is returned.

16558

If locale is omitted or None, the current setting for

16559

category is returned.

16560

setlocale() is not thread safe on most systems.

16561

Applications typically start with a call of

16562

import locale

16563

locale.setlocale(locale.LC_ALL, '')

16564

This sets the locale for all categories to the user's default

16565

setting (typically specified in the LANG environment

16566

variable). If the locale is not changed thereafter, using

16567

multithreading should not cause problems.

16568

Changed in version 2.0: Added support for tuple values of the locale

16569

parameter</description>

16570

<param name="category" optional="0">category</param><param name="locale" optional="1">locale</param>

16571

<insert>setlocale(category, [locale])</insert><dialog title="Insert setlocale">setlocale(%0, %1)</dialog><info title="Info window"></info></function>

16572

16573

16574

<description>Returns the database of the local conventions as a dictionary.

16575

This dictionary has the following strings as keys:

16576

{l|l|p{3in}}{constant}{Key}{Category}{Meaning}

16577

LC_NUMERIC{'decimal_point'}

16578

{Decimal point character.}

16579

{'grouping'}

16580

{Sequence of numbers specifying which relative positions

16581

the 'thousands_sep' is expected. If the sequence is

16582

terminated with CHAR_MAX, no further grouping

16583

is performed. If the sequence terminates with a 0, the last group size is repeatedly used.}

16584

{'thousands_sep'}

16585

{Character used between groups.}

16586

LC_MONETARY{'int_curr_symbol'}

16587

{International currency symbol.}

16588

{'currency_symbol'}

16589

{Local currency symbol.}

16590

{'mon_decimal_point'}

16591

{Decimal point used for monetary values.}

16592

{'mon_thousands_sep'}

16593

{Group separator used for monetary values.}

16594

{'mon_grouping'}

16595

{Equivalent to 'grouping', used for monetary

16596

values.}

16597

{'positive_sign'}

16598

{Symbol used to annotate a positive monetary value.}

16599

{'negative_sign'}

16600

{Symbol used to annotate a nnegative monetary value.}

16601

{'frac_digits'}

16602

{Number of fractional digits used in local formatting

16603

of monetary values.}

16604

{'int_frac_digits'}

16605

{Number of fractional digits used in international

16606

formatting of monetary values.}

16607

The possible values for 'p_sign_posn' and

16608

'n_sign_posn' are given below.

16609

{c|l}{code}{Value}{Explanation}

16610

0{Currency and value are surrounded by parentheses.}

16611

1{The sign should precede the value and currency symbol.}

16612

2{The sign should follow the value and currency symbol.}

16613

3{The sign should immediately precede the value.}

16614

4{The sign should immediately follow the value.}

16615

LC_MAX{Nothing is specified in this locale.}

16616

</description>

16617

16618

<insert>localeconv()</insert><dialog title="Insert localeconv">localeconv()</dialog><info title="Info window"></info></function>

16619

16620

16621

<description>Return some locale-specific information as a string. This function is

16622

not available on all systems, and the set of possible options might

16623

also vary across platforms. The possible argument values are numbers,

16624

for which symbolic constants are available in the locale module.</description>

16625

<param name="optionoption" optional="0">optionoption</param>

16626

<insert>nl_langinfo(optionoption)</insert><dialog title="Insert nl_langinfo">nl_langinfo(%0)</dialog><info title="Info window"></info></function>

16627

16628

16629

<description>Tries to determine the default locale settings and returns

16630

them as a tuple of the form (language code,

16631

encoding).

16632

According to , a program which has not called

16633

setlocale(LC_ALL, '') runs using the portable 'C'

16634

locale. Calling setlocale(LC_ALL, '') lets it use the

16635

default locale as defined by the LANG variable. Since we

16636

do not want to interfere with the current locale setting we thus

16637

emulate the behavior in the way described above.

16638

To maintain compatibility with other platforms, not only the

16639

LANG variable is tested, but a list of variables given as

16640

envvars parameter. The first found to be defined will be

16641

used. envvars defaults to the search path used in GNU gettext;

16642

it must always contain the variable name LANG. The GNU

16643

gettext search path contains 'LANGUAGE', 'LC_ALL',

16644

'LC_CTYPE', and 'LANG', in that order.

16645

Except for the code 'C', the language code corresponds to

16646

1766. language code and encoding may be

16647

None if their values cannot be determined.

16648

New in version 2.0</description>

16649

<param name="envvars" optional="0">envvars</param>

16650

<insert>getdefaultlocale(envvars)</insert><dialog title="Insert getdefaultlocale">getdefaultlocale(%0)</dialog><info title="Info window"></info></function>

16651

16652

16653

<description>Returns the current setting for the given locale category as

16654

sequence containing language code, encoding.

16655

category may be one of the LC_* values except

16656

LC_ALL. It defaults to LC_CTYPE.

16657

Except for the code 'C', the language code corresponds to

16658

1766. language code and encoding may be

16659

None if their values cannot be determined.

16660

New in version 2.0</description>

16661

<param name="category" optional="0">category</param>

16662

<insert>getlocale(category)</insert><dialog title="Insert getlocale">getlocale(%0)</dialog><info title="Info window"></info></function>

16663

16664

16665

<description>Return the encoding used for text data, according to user

16666

preferences. User preferences are expressed differently on

16667

different systems, and might not be available programmatically on

16668

some systems, so this function only returns a guess.

16669

On some systems, it is necessary to invoke setlocale

16670

to obtain the user preferences, so this function is not thread-safe.

16671

If invoking setlocale is not necessary or desired, do_setlocale

16672

should be set to False.

16673

New in version 2.3</description>

16674

<param name="do_setlocale" optional="0">do_setlocale</param>

16675

<insert>getpreferredencoding(do_setlocale)</insert><dialog title="Insert getpreferredencoding">getpreferredencoding(%0)</dialog><info title="Info window"></info></function>

16676

16677

16678

<description>Returns a normalized locale code for the given locale name. The

16679

returned locale code is formatted for use with

16680

setlocale(). If normalization fails, the original name

16681

is returned unchanged.

16682

If the given encoding is not known, the function defaults to

16683

the default encoding for the locale code just like

16684

setlocale().

16685

New in version 2.0</description>

16686

<param name="localenamelocalename" optional="0">localenamelocalename</param>

16687

<insert>normalize(localenamelocalename)</insert><dialog title="Insert normalize">normalize(%0)</dialog><info title="Info window"></info></function>

16688

16689

16690

<description>Sets the locale for category to the default setting.

16691

The default setting is determined by calling

16692

getdefaultlocale(). category defaults to

16693

LC_ALL.

16694

New in version 2.0</description>

16695

<param name="category" optional="0">category</param>

16696

<insert>resetlocale(category)</insert><dialog title="Insert resetlocale">resetlocale(%0)</dialog><info title="Info window"></info></function>

16697

16698

16699

<description>Compares two strings according to the current

16700

LC_COLLATE setting. As any other compare function,

16701

returns a negative, or a positive value, or 0, depending on

16702

whether string1 collates before or after string2 or is

16703

equal to it.</description>

16704

<param name="string1" optional="0">string1</param><param name="string2 string2" optional="0">string2 string2</param>

16705

<insert>strcoll(string1, string2 string2)</insert><dialog title="Insert strcoll">strcoll(%0, %1)</dialog><info title="Info window"></info></function>

16706

16707

16708

<description>Transforms a string to one that can be used for the built-in

16709

function cmp()cmp, and still returns

16710

locale-aware results. This function can be used when the same

16711

string is compared repeatedly, e.g. when collating a sequence of

16712

strings.</description>

16713

<param name="stringstring" optional="0">stringstring</param>

16714

<insert>strxfrm(stringstring)</insert><dialog title="Insert strxfrm">strxfrm(%0)</dialog><info title="Info window"></info></function>

16715

16716

16717

<description>Formats a number val according to the current

16718

LC_NUMERIC setting. The format follows the conventions

16719

of the % operator. For floating point values, the decimal

16720

point is modified if appropriate. If grouping is true, also

16721

takes the grouping into account.</description>

16722

<param name="format" optional="0">format</param><param name="val" optional="0">val</param><param name="grouping" optional="1">grouping</param>

16723

<insert>format(format, val, [grouping])</insert><dialog title="Insert format">format(%0, %1, %2)</dialog><info title="Info window"></info></function>

16724

16725

16726

<description>Formats a floating point number using the same format as the

16727

built-in function str(float), but takes the decimal

16728

point into account.</description>

16729

<param name="floatfloat" optional="0">floatfloat</param>

16730

<insert>str(floatfloat)</insert><dialog title="Insert str">str(%0)</dialog><info title="Info window"></info></function>

16731

16732

16733

<description>Converts a string to a floating point number, following the

16734

LC_NUMERIC settings.</description>

16735

<param name="stringstring" optional="0">stringstring</param>

16736

<insert>atof(stringstring)</insert><dialog title="Insert atof">atof(%0)</dialog><info title="Info window"></info></function>

16737

16738

16739

<description>Converts a string to an integer, following the

16740

LC_NUMERIC conventions.</description>

16741

<param name="stringstring" optional="0">stringstring</param>

16742

<insert>atoi(stringstring)</insert><dialog title="Insert atoi">atoi(%0)</dialog><info title="Info window"></info></function>

16743

16744

16745

<description>The C standard defines the locale as a program-wide property that may

16746

be relatively expensive to change. On top of that, some

16747

implementation are broken in such a way that frequent locale changes

16748

may cause core dumps. This makes the locale somewhat painful to use

16749

correctly.

16750

Initially, when a program is started, the locale is the C locale, no

16751

matter what the user's preferred locale is. The program must

16752

explicitly say that it wants the user's preferred locale settings by

16753

calling setlocale(LC_ALL, '').

16754

It is generally a bad idea to call setlocale() in some library

16755

routine, since as a side effect it affects the entire program. Saving

16756

and restoring it is almost as bad: it is expensive and affects other

16757

threads that happen to run before the settings have been restored.

16758

If, when coding a module for general use, you need a locale

16759

independent version of an operation that is affected by the locale

16760

(such as string.lower(), or certain formats used with

16761

time.strftime()), you will have to find a way to do it

16762

without using the standard library routine. Even better is convincing

16763

yourself that using locale settings is okay. Only as a last resort

16764

should you document that your module is not compatible with

16765

non-C locale settings.

16766

The case conversion functions in the

16767

stringstring module are affected by the

16768

locale settings. When a call to the setlocale() function

16769

changes the LC_CTYPE settings, the variables

16770

string.lowercase, string.uppercase and

16771

string.letters are recalculated. Note that this code that uses

16772

these variable through `from ... import ...',

16773

e.g. from string import letters, is not affected by subsequent

16774

setlocale() calls.

16775

The only way to perform numeric operations according to the locale

16776

is to use the special functions defined by this module:

16777

atof(), atoi(), format(),

16778

str().

16779

</description>

16780

</group>

16781

16782

<description>Extension modules should never call setlocale(), except to

16783

find out what the current locale is. But since the return value can

16784

only be used portably to restore it, that is not very useful (except

16785

perhaps to find out whether or not the locale is C).

16786

When Python is embedded in an application, if the application sets the

16787

locale to something specific before initializing Python, that is

16788

generally okay, and Python will use whatever locale is set,

16789

except that the LC_NUMERIC locale should always be

16790

C.

16791

The setlocale() function in the locale module

16792

gives the Python programmer the impression that you can manipulate the

16793

LC_NUMERIC locale setting, but this not the case at the C

16794

level: C code will always find that the LC_NUMERIC locale

16795

setting is C. This is because too much would break when the

16796

decimal point character is set to something else than a period

16797

(e.g. the Python parser would break). Caveat: threads that run

16798

without holding Python's global interpreter lock may occasionally find

16799

that the numeric locale setting differs; this is because the only

16800

portable way to implement this feature is to set the numeric locale

16801

settings to what the user requests, extract the relevant

16802

characteristics, and then restore the C numeric locale.

16803

When Python code uses the locale module to change the locale,

16804

this also affects the embedding application. If the embedding

16805

application doesn't want this to happen, it should remove the

16806

_locale extension module (which does all the work) from the

16807

table of built-in modules in the config.c file, and make sure

16808

that the _locale module is not accessible as a shared library.

16809

</description>

16810

</group>

16811

16812

</group>

16813

</group>

16814

16815

<description>Multilingual internationalization services.

16816

The gettext module provides internationalization (I18N) and

16817

localization (L10N) services for your Python modules and applications.

16818

It supports both the GNU gettext message catalog API and a

16819

higher level, class-based API that may be more appropriate for Python

16820

files. The interface described below allows you to write your

16821

module and application messages in one natural language, and provide a

16822

catalog of translated messages for running under different natural

16823

languages.

16824

Some hints on localizing your Python modules and applications are also

16825

given.

16826

</description>

16827

16828

<description>The gettext module defines the following API, which is very

16829

similar to the GNU gettext API. If you use this API you

16830

will affect the translation of your entire application globally. Often

16831

this is what you want if your application is monolingual, with the choice

16832

of language dependent on the locale of your user. If you are

16833

localizing a Python module, or if your application needs to switch

16834

languages on the fly, you probably want to use the class-based API

16835

instead.

16836

</description>

16837

16838

<description>Bind the domain to the locale directory

16839

localedir. More concretely, gettext will look for

16840

binary .mo files for the given domain using the path (on ):

16841

localedir/language/LC_MESSAGES/domain.mo,

16842

where languages is searched for in the environment variables

16843

LANGUAGE, LC_ALL, LC_MESSAGES, and

16844

LANG respectively.

16845

If localedir is omitted or None, then the current binding

16846

for domain is returned.

16847

The default locale directory is system dependent; for example,

16848

on RedHat Linux it is /usr/share/locale, but on Solaris

16849

it is /usr/lib/locale. The gettext module

16850

does not try to support these system dependent defaults;

16851

instead its default is sys.prefix/share/locale.

16852

For this reason, it is always best to call

16853

bindtextdomain() with an explicit absolute path at

16854

the start of your application.</description>

16855

<param name="domain" optional="0">domain</param><param name="localedir" optional="1">localedir</param>

16856

<insert>bindtextdomain(domain, [localedir])</insert><dialog title="Insert bindtextdomain">bindtextdomain(%0, %1)</dialog><info title="Info window"></info></function>

16857

16858

16859

<description>Change or query the current global domain. If domain is

16860

None, then the current global domain is returned, otherwise the

16861

global domain is set to domain, which is returned.</description>

16862

<param name="domain" optional="0">domain</param>

16863

<insert>textdomain(domain)</insert><dialog title="Insert textdomain">textdomain(%0)</dialog><info title="Info window"></info></function>

16864

16865

16866

<description>Return the localized translation of message, based on the

16867

current global domain, language, and locale directory. This function

16868

is usually aliased as _ in the local namespace (see

16869

examples below).</description>

16870

<param name="messagemessage" optional="0">messagemessage</param>

16871

<insert>gettext(messagemessage)</insert><dialog title="Insert gettext">gettext(%0)</dialog><info title="Info window"></info></function>

16872

16873

16874

<description>Like gettext(), but look the message up in the specified

16875

domain.</description>

16876

<param name="domain" optional="0">domain</param><param name="message message" optional="0">message message</param>

16877

<insert>dgettext(domain, message message)</insert><dialog title="Insert dgettext">dgettext(%0, %1)</dialog><info title="Info window"></info></function>

16878

16879

16880

<description>Like gettext(), but consider plural forms. If a translation

16881

is found, apply the plural formula to n, and return the

16882

resulting message (some languages have more than two plural forms).

16883

If no translation is found, return singular if n is 1;

16884

return plural otherwise.

16885

The Plural formula is taken from the catalog header. It is a C or

16886

Python expression that has a free variable n; the expression evaluates

16887

to the index of the plural in the catalog. See the GNU gettext

16888

documentation for the precise syntax to be used in .po files, and the

16889

formulas for a variety of languages.

16890

New in version 2.3</description>

16891

<param name="singular" optional="0">singular</param><param name="plural" optional="0">plural</param><param name="n n" optional="0">n n</param>

16892

<insert>ngettext(singular, plural, n n)</insert><dialog title="Insert ngettext">ngettext(%0, %1, %2)</dialog><info title="Info window"></info></function>

16893

16894

16895

<description>Like ngettext(), but look the message up in the specified

16896

domain.

16897

New in version 2.3</description>

16898

<param name="domain" optional="0">domain</param><param name="singular" optional="0">singular</param><param name="plural" optional="0">plural</param><param name="n n" optional="0">n n</param>

16899

<insert>dngettext(domain, singular, plural, n n)</insert><dialog title="Insert dngettext">dngettext(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

16900

16901

</group>

16902

16903

<description>The class-based API of the gettext module gives you more

16904

flexibility and greater convenience than the GNU gettext

16905

API. It is the recommended way of localizing your Python applications and

16906

modules. gettext defines a ``translations'' class which

16907

implements the parsing of GNU .mo format files, and has methods

16908

for returning either standard 8-bit strings or Unicode strings.

16909

Translations instances can also install themselves in the built-in

16910

namespace as the function _().

16911

</description>

16912

16913

<description>This function implements the standard .mo file search

16914

algorithm. It takes a domain, identical to what

16915

textdomain() takes. Optional localedir is as in

16916

bindtextdomain() Optional languages is a list of

16917

strings, where each string is a language code.

16918

If localedir is not given, then the default system locale

16919

directory is used.See the footnote for

16920

bindtextdomain() above. If languages is not given,

16921

then the following environment variables are searched: LANGUAGE,

16922

LC_ALL, LC_MESSAGES, and LANG. The first one

16923

returning a non-empty value is used for the languages variable.

16924

The environment variables should contain a colon separated list of

16925

languages, which will be split on the colon to produce the expected

16926

list of language code strings.

16927

find() then expands and normalizes the languages, and then

16928

iterates through them, searching for an existing file built of these

16929

components:

16930

localedir/language/LC_MESSAGES/domain.mo

16931

The first such file name that exists is returned by find().

16932

If no such file is found, then None is returned. If all

16933

is given, it returns a list of all file names, in the order in which

16934

they appear in the languages list or the environment variables.</description>

16935

<param name="domain" optional="0">domain</param><param name="localedir" optional="1">localedir</param><param name="languages" optional="1">languages</param><param name="all" optional="1">all</param>

16936

<insert>find(domain, [localedir], [languages], [all])</insert><dialog title="Insert find">find(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

16937

16938

16939

<description>Return a Translations instance based on the domain,

16940

localedir, and languages, which are first passed to

16941

find() to get a list of the

16942

associated .mo file paths. Instances with

16943

identical .mo file names are cached. The actual class instantiated

16944

is either class_ if provided, otherwise

16945

GNUTranslations. The class's constructor must take a single

16946

file object argument. If multiple files are found, later files are used as fallbacks for

16947

earlier ones. To allow setting the fallback, copy.copy

16948

is used to clone each translation object from the cache; the actual

16949

instance data is still shared with the cache.

16950

If no .mo file is found, this function raises

16951

IOError if fallback is false (which is the default),

16952

and returns a NullTranslations instance if fallback is

16953

true.</description>

16954

<param name="domain" optional="0">domain</param><param name="localedir" optional="1">localedir</param><param name="languages" optional="1">languages</param><param name="class_" optional="1">class_</param><param name="fallback" optional="1">fallback</param>

16955

<insert>translation(domain, [localedir], [languages], [class_], [fallback])</insert><dialog title="Insert translation">translation(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

16956

16957

16958

<description>This installs the function _ in Python's builtin namespace,

16959

based on domain, and localedir which are passed to the

16960

function translation(). The unicode flag is passed to

16961

the resulting translation object's install method.

16962

As seen below, you usually mark the strings in your application that are

16963

candidates for translation, by wrapping them in a call to the

16964

_() function, like this:

16965

print _('This string will be translated.')

16966

For convenience, you want the _() function to be installed in

16967

Python's builtin namespace, so it is easily accessible in all modules

16968

of your application.</description>

16969

<param name="domain" optional="0">domain</param><param name="localedir" optional="1">localedir</param><param name="unicode" optional="1">unicode</param>

16970

<insert>install(domain, [localedir], [unicode])</insert><dialog title="Insert install">install(%0, %1, %2)</dialog><info title="Info window"></info></function>

16971

16972

16973

<description>Takes an optional file object fp, which is ignored by the base

16974

class. Initializes ``protected'' instance variables _info and

16975

_charset which are set by derived classes, as well as _fallback,

16976

which is set through add_fallback. It then calls

16977

self._parse(fp) if fp is not None.</description>

16978

16979

16980

16981

16982

<description>No-op'd in the base class, this method takes file object fp, and

16983

reads the data from the file, initializing its message catalog. If

16984

you have an unsupported message catalog file format, you should

16985

override this method to parse your format.</description>

16986

16987

<insert>_parse(fpfp)</insert><dialog title="Insert _parse">_parse(%0)</dialog><info title="Info window"></info></function>

16988

16989

16990

<description>Add fallback as the fallback object for the current translation

16991

object. A translation object should consult the fallback if it cannot

16992

provide a translation for a given message.</description>

16993

<param name="fallbackfallback" optional="0">fallbackfallback</param>

16994

<insert>add_fallback(fallbackfallback)</insert><dialog title="Insert add_fallback">add_fallback(%0)</dialog><info title="Info window"></info></function>

16995

16996

16997

<description>If a fallback has been set, forward gettext to the fallback.

16998

Otherwise, return the translated message. Overridden in derived classes.</description>

16999

<param name="messagemessage" optional="0">messagemessage</param>

17000

<insert>gettext(messagemessage)</insert><dialog title="Insert gettext">gettext(%0)</dialog><info title="Info window"></info></function>

17001

17002

17003

<description>If a fallback has been set, forward ugettext to the fallback.

17004

Otherwise, return the translated message as a Unicode string.

17005

Overridden in derived classes.</description>

17006

<param name="messagemessage" optional="0">messagemessage</param>

17007

<insert>ugettext(messagemessage)</insert><dialog title="Insert ugettext">ugettext(%0)</dialog><info title="Info window"></info></function>

17008

17009

17010

<description>If a fallback has been set, forward ngettext to the fallback.

17011

Otherwise, return the translated message. Overridden in derived classes.

17012

New in version 2.3</description>

17013

<param name="singular" optional="0">singular</param><param name="plural" optional="0">plural</param><param name="n n" optional="0">n n</param>

17014

<insert>ngettext(singular, plural, n n)</insert><dialog title="Insert ngettext">ngettext(%0, %1, %2)</dialog><info title="Info window"></info></function>

17015

17016

17017

<description>If a fallback has been set, forward ungettext to the fallback.

17018

Otherwise, return the translated message as a Unicode string.

17019

Overridden in derived classes.

17020

New in version 2.3</description>

17021

<param name="singular" optional="0">singular</param><param name="plural" optional="0">plural</param><param name="n n" optional="0">n n</param>

17022

<insert>ungettext(singular, plural, n n)</insert><dialog title="Insert ungettext">ungettext(%0, %1, %2)</dialog><info title="Info window"></info></function>

17023

17024

17025

<description>Return the ``protected'' _info variable.</description>

17026

17027

17028

17029

17030

<description>Return the ``protected'' _charset variable.</description>

17031

17032

<insert>charset()</insert><dialog title="Insert charset">charset()</dialog><info title="Info window"></info></function>

17033

17034

17035

<description>If the unicode flag is false, this method installs

17036

self.gettext() into the built-in namespace, binding it to

17037

_. If unicode is true, it binds self.ugettext()

17038

instead. By default, unicode is false.

17039

Note that this is only one way, albeit the most convenient way, to

17040

make the _ function available to your application. Because it

17041

affects the entire application globally, and specifically the built-in

17042

namespace, localized modules should never install _.

17043

Instead, they should use this code to make _ available to

17044

their module:

17045

import gettext

17046

t = gettext.translation('mymodule', ...)

17047

_ = t.gettext

17048

This puts _ only in the module's global namespace and so

17049

only affects calls within this module.</description>

17050

<param name="unicode" optional="0">unicode</param>

17051

<insert>install(unicode)</insert><dialog title="Insert install">install(%0)</dialog><info title="Info window"></info></function>

17052

17053

17054

<description>Look up the message id in the catalog and return the

17055

corresponding message string, as an 8-bit string encoded with the

17056

catalog's charset encoding, if known. If there is no entry in the

17057

catalog for the message id, and a fallback has been set, the

17058

look up is forwarded to the fallback's gettext() method.

17059

Otherwise, the message id is returned.</description>

17060

<param name="messagemessage" optional="0">messagemessage</param>

17061

<insert>gettext(messagemessage)</insert><dialog title="Insert gettext">gettext(%0)</dialog><info title="Info window"></info></function>

17062

17063

17064

<description>Look up the message id in the catalog and return the

17065

corresponding message string, as a Unicode string. If there is no

17066

entry in the catalog for the message id, and a fallback has been

17067

set, the look up is forwarded to the fallback's ugettext()

17068

method. Otherwise, the message id is returned.</description>

17069

<param name="messagemessage" optional="0">messagemessage</param>

17070

<insert>ugettext(messagemessage)</insert><dialog title="Insert ugettext">ugettext(%0)</dialog><info title="Info window"></info></function>

17071

17072

17073

<description>Do a plural-forms lookup of a message id. singular is used as

17074

the message id for purposes of lookup in the catalog, while n is

17075

used to determine which plural form to use. The returned message

17076

string is an 8-bit string encoded with the catalog's charset encoding,

17077

if known.

17078

If the message id is not found in the catalog, and a fallback is

17079

specified, the request is forwarded to the fallback's

17080

ngettext() method. Otherwise, when n is 1 singular is

17081

returned, and plural is returned in all other cases.

17082

New in version 2.3</description>

17083

<param name="singular" optional="0">singular</param><param name="plural" optional="0">plural</param><param name="n n" optional="0">n n</param>

17084

<insert>ngettext(singular, plural, n n)</insert><dialog title="Insert ngettext">ngettext(%0, %1, %2)</dialog><info title="Info window"></info></function>

17085

17086

17087

<description>Do a plural-forms lookup of a message id. singular is used as

17088

the message id for purposes of lookup in the catalog, while n is

17089

used to determine which plural form to use. The returned message

17090

string is a Unicode string.

17091

If the message id is not found in the catalog, and a fallback is

17092

specified, the request is forwarded to the fallback's

17093

ungettext() method. Otherwise, when n is 1 singular is

17094

returned, and plural is returned in all other cases.

17095

Here is an example:

17096

n = len(os.listdir('.'))

17097

cat = GNUTranslations(somefile)

17098

message = cat.ungettext(

17099

'There is %(num)d file in this directory',

17100

'There are %(num)d files in this directory',

17101

n) % {'n': n}

17102

New in version 2.3</description>

17103

<param name="singular" optional="0">singular</param><param name="plural" optional="0">plural</param><param name="n n" optional="0">n n</param>

17104

<insert>ungettext(singular, plural, n n)</insert><dialog title="Insert ungettext">ungettext(%0, %1, %2)</dialog><info title="Info window"></info></function>

17105

17106

</group>

17107

17108

<description>Internationalization (I18N) refers to the operation by which a program

17109

is made aware of multiple languages. Localization (L10N) refers to

17110

the adaptation of your program, once internationalized, to the local

17111

language and cultural habits. In order to provide multilingual

17112

messages for your Python programs, you need to take the following

17113

steps:

17114

prepare your program or module by specially marking

17115

translatable strings

17116

run a suite of tools over your marked files to generate raw

17117

messages catalogs

17118

create language specific translations of the message catalogs

17119

use the gettext module so that message strings are

17120

properly translated

17121

In order to prepare your code for I18N, you need to look at all the

17122

strings in your files. Any string that needs to be translated

17123

should be marked by wrapping it in _('...') --- that is, a call

17124

to the function _(). For example:

17125

filename = 'mylog.txt'

17126

message = _('writing a log message')

17127

fp = open(filename, 'w')

17128

fp.write(message)

17129

fp.close()

17130

In this example, the string 'writing a log message' is marked as

17131

a candidate for translation, while the strings 'mylog.txt' and

17132

'w' are not.

17133

The Python distribution comes with two tools which help you generate

17134

the message catalogs once you've prepared your source code. These may

17135

or may not be available from a binary distribution, but they can be

17136

found in a source distribution, in the Tools/i18n directory.

17137

The pygettextFran cois Pinard has

17138

written a program called

17139

xpot which does a similar job. It is available as part of

17140

his po-utils package at

17141

http://www.iro.umontreal.ca/contrib/po-utils/HTML/. program

17142

scans all your Python source code looking for the strings you

17143

previously marked as translatable. It is similar to the GNU

17144

gettext program except that it understands all the

17145

intricacies of Python source code, but knows nothing about C or Cpp

17146

source code. You don't need GNU gettext unless you're also

17147

going to be translating C code (such as C extension modules).

17148

pygettext generates textual Uniforum-style human readable

17149

message catalog .pot files, essentially structured human

17150

readable files which contain every marked string in the source code,

17151

along with a placeholder for the translation strings.

17152

pygettext is a command line script that supports a similar

17153

command line interface as xgettext; for details on its use,

17154

run:

17155

pygettext.py --help

17156

Copies of these .pot files are then handed over to the

17157

individual human translators who write language-specific versions for

17158

every supported natural language. They send you back the filled in

17159

language-specific versions as a .po file. Using the

17160

msgfmt.pymsgfmt.py is binary

17161

compatible with GNU msgfmt except that it provides a

17162

simpler, all-Python implementation. With this and

17163

pygettext.py, you generally won't need to install the GNU

17164

gettext package to internationalize your Python

17165

applications. program (in the Tools/i18n directory), you take the

17166

.po files from your translators and generate the

17167

machine-readable .mo binary catalog files. The .mo

17168

files are what the gettext module uses for the actual

17169

translation processing during run-time.

17170

How you use the gettext module in your code depends on

17171

whether you are internationalizing your entire application or a single

17172

module.

17173

Localizing your module

17174

If you are localizing your module, you must take care not to make

17175

global changes, e.g. to the built-in namespace. You should not use

17176

the GNU gettext API but instead the class-based API. Let's say your module is called ``spam'' and the module's various

17177

natural language translation .mo files reside in

17178

/usr/share/locale in GNU gettext format. Here's what

17179

you would put at the top of your module:

17180

import gettext

17181

t = gettext.translation('spam', '/usr/share/locale')

17182

_ = t.gettext

17183

If your translators were providing you with Unicode strings in their

17184

.po files, you'd instead do:

17185

import gettext

17186

t = gettext.translation('spam', '/usr/share/locale')

17187

_ = t.ugettext

17188

Localizing your application

17189

If you are localizing your application, you can install the _()

17190

function globally into the built-in namespace, usually in the main driver file

17191

of your application. This will let all your application-specific

17192

files just use _('...') without having to explicitly install it in

17193

each file.

17194

In the simple case then, you need only add the following bit of code

17195

to the main driver file of your application:

17196

import gettext

17197

gettext.install('myapplication')

17198

If you need to set the locale directory or the unicode flag,

17199

you can pass these into the install() function:

17200

import gettext

17201

gettext.install('myapplication', '/usr/share/locale', unicode=1)

17202

Changing languages on the fly

17203

If your program needs to support many languages at the same time, you

17204

may want to create multiple translation instances and then switch

17205

between them explicitly, like so:

17206

import gettext

17207

lang1 = gettext.translation(languages=['en'])

17208

lang2 = gettext.translation(languages=['fr'])

17209

lang3 = gettext.translation(languages=['de'])

17210

# start by using language1

17211

lang1.install()

17212

# ... time goes by, user selects language 2

17213

lang2.install()

17214

# ... more time goes by, user selects language 3

17215

lang3.install()

17216

Deferred translations

17217

In most coding situations, strings are translated where they are coded.

17218

Occasionally however, you need to mark strings for translation, but

17219

defer actual translation until later. A classic example is:

17220

animals = ['mollusk',

17221

'albatross',

17222

'rat',

17223

'penguin',

17224

'python',

17225

]

17226

# ...

17227

for a in animals:

17228

print a

17229

Here, you want to mark the strings in the animals list as being

17230

translatable, but you don't actually want to translate them until they

17231

are printed.

17232

Here is one way you can handle this situation:

17233

def _(message): return message

17234

animals = [_('mollusk'),

17235

_('albatross'),

17236

_('rat'),

17237

_('penguin'),

17238

_('python'),

17239

]

17240

del _

17241

# ...

17242

for a in animals:

17243

print _(a)

17244

This works because the dummy definition of _() simply returns

17245

the string unchanged. And this dummy definition will temporarily

17246

override any definition of _() in the built-in namespace

17247

(until the del command).

17248

Take care, though if you have a previous definition of _ in

17249

the local namespace.

17250

Note that the second use of _() will not identify ``a'' as

17251

being translatable to the pygettext program, since it is not

17252

a string.

17253

Another way to handle this is with the following example:

17254

def N_(message): return message

17255

animals = [N_('mollusk'),

17256

N_('albatross'),

17257

N_('rat'),

17258

N_('penguin'),

17259

N_('python'),

17260

]

17261

# ...

17262

for a in animals:

17263

print _(a)

17264

In this case, you are marking translatable strings with the function

17265

N_(),The choice of N_() here is totally

17266

arbitrary; it could have just as easily been

17267

MarkThisStringForTranslation().

17268

which won't conflict with any definition of

17269

_(). However, you will need to teach your message extraction

17270

program to look for translatable strings marked with N_().

17271

pygettext and xpot both support this through the

17272

use of command line switches.

17273

</description>

17274

</group>

17275

17276

</group>

17277

</group>

17278

17279

<description>% These apply to all modules, and may be given more than once:

17280

Logging module for Python based on 282.

17281

New in version 2.3

17282

This module defines functions and classes which implement a flexible

17283

error logging system for applications.

17284

Logging is performed by calling methods on instances of the

17285

Logger class (hereafter called loggers). Each instance has a

17286

name, and they are conceptually arranged in a name space hierarchy

17287

using dots (periods) as separators. For example, a logger named

17288

"scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf".

17289

Logger names can be anything you want, and indicate the area of an

17290

application in which a logged message originates.

17291

Logged messages also have levels of importance associated with them.

17292

The default levels provided are DEBUG, INFO,

17293

WARNING, ERROR and CRITICAL. As a

17294

convenience, you indicate the importance of a logged message by calling

17295

an appropriate method of Logger. The methods are

17296

debug(), info(), warning(), error() and

17297

critical(), which mirror the default levels. You are not

17298

constrained to use these levels: you can specify your own and use a

17299

more general Logger method, log(), which takes an

17300

explicit level argument.

17301

Levels can also be associated with loggers, being set either by the

17302

developer or through loading a saved logging configuration. When a

17303

logging method is called on a logger, the logger compares its own

17304

level with the level associated with the method call. If the logger's

17305

level is higher than the method call's, no logging message is actually

17306

generated. This is the basic mechanism controlling the verbosity of

17307

logging output.

17308

Logging messages are encoded as instances of the LogRecord class.

17309

When a logger decides to actually log an event, an LogRecord

17310

instance is created from the logging message.

17311

Logging messages are subjected to a dispatch mechanism through the

17312

use of handlers, which are instances of subclasses of the

17313

Handler class. Handlers are responsible for ensuring that a logged

17314

message (in the form of a LogRecord) ends up in a particular

17315

location (or set of locations) which is useful for the target audience for

17316

that message (such as end users, support desk staff, system administrators,

17317

developers). Handlers are passed LogRecord instances intended for

17318

particular destinations. Each logger can have zero, one or more handlers

17319

associated with it (via the addHandler method of Logger).

17320

In addition to any handlers directly associated with a logger,

17321

all handlers associated with all ancestors of the logger are

17322

called to dispatch the message.

17323

Just as for loggers, handlers can have levels associated with them.

17324

A handler's level acts as a filter in the same way as a logger's level does.

17325

If a handler decides to actually dispatch an event, the emit() method

17326

is used to send the message to its destination. Most user-defined subclasses

17327

of Handler will need to override this emit().

17328

In addition to the base Handler class, many useful subclasses

17329

are provided:

17330

StreamHandler instances send error messages to

17331

streams (file-like objects).

17332

FileHandler instances send error messages to disk

17333

files.

17334

RotatingFileHandler instances send error messages to disk

17335

files, with support for maximum log file sizes and log file rotation.

17336

SocketHandler instances send error messages to

17337

TCP/IP sockets.

17338

DatagramHandler instances send error messages to UDP

17339

sockets.

17340

SMTPHandler instances send error messages to a

17341

designated email address.

17342

SysLogHandler instances send error messages to a

17343

syslog daemon, possibly on a remote machine.

17344

NTEventLogHandler instances send error messages to a

17345

Windows NT/2000/XP event log.

17346

MemoryHandler instances send error messages to a

17347

buffer in memory, which is flushed whenever specific criteria are

17348

met.

17349

HTTPHandler instances send error messages to an

17350

HTTP server using either GET or POST semantics.

17351

The StreamHandler and FileHandler classes are defined

17352

in the core logging package. The other handlers are defined in a sub-

17353

module, logging.handlers. (There is also another sub-module,

17354

logging.config, for configuration functionality.)

17355

Logged messages are formatted for presentation through instances of the

17356

Formatter class. They are initialized with a format string

17357

suitable for use with the % operator and a dictionary.

17358

For formatting multiple messages in a batch, instances of

17359

BufferingFormatter can be used. In addition to the format string

17360

(which is applied to each message in the batch), there is provision for

17361

header and trailer format strings.

17362

When filtering based on logger level and/or handler level is not enough,

17363

instances of Filter can be added to both Logger and

17364

Handler instances (through their addFilter() method).

17365

Before deciding to process a message further, both loggers and handlers

17366

consult all their filters for permission. If any filter returns a false

17367

value, the message is not processed further.

17368

The basic Filter functionality allows filtering by specific logger

17369

name. If this feature is used, messages sent to the named logger and its

17370

children are allowed through the filter, and all others dropped.

17371

In addition to the classes described above, there are a number of module-

17372

level functions.

17373

</description>

17374

17375

<description>Return a logger with the specified name or, if no name is specified, return

17376

a logger which is the root logger of the hierarchy.

17377

All calls to this function with a given name return the same logger instance.

17378

This means that logger instances never need to be passed between different

17379

parts of an application.</description>

17380

17381

<insert>getLogger(name)</insert><dialog title="Insert getLogger">getLogger(%0)</dialog><info title="Info window"></info></function>

17382

17383

17384

<description>Logs a message with level DEBUG on the root logger.

17385

The msg is the message format string, and the args are the

17386

arguments which are merged into msg. The only keyword argument in

17387

kwargs which is inspected is exc_info which, if it does not

17388

evaluate as false, causes exception information (via a call to

17389

sys.exc_info()) to be added to the logging message.</description>

17390

<param name="msg" optional="0">msg</param><param name="*args" optional="1">*args</param><param name="**kwargs" optional="1">**kwargs</param>

17391

<insert>debug(msg, [*args], [**kwargs])</insert><dialog title="Insert debug">debug(%0, %1, %2)</dialog><info title="Info window"></info></function>

17392

17393

17394

<description>Logs a message with level INFO on the root logger.

17395

The arguments are interpreted as for debug().</description>

17396

<param name="msg" optional="0">msg</param><param name="*args" optional="1">*args</param><param name="**kwargs" optional="1">**kwargs</param>

17397

<insert>info(msg, [*args], [**kwargs])</insert><dialog title="Insert info">info(%0, %1, %2)</dialog><info title="Info window"></info></function>

17398

17399

17400

<description>Logs a message with level WARNING on the root logger.

17401

The arguments are interpreted as for debug().</description>

17402

<param name="msg" optional="0">msg</param><param name="*args" optional="1">*args</param><param name="**kwargs" optional="1">**kwargs</param>

17403

<insert>warning(msg, [*args], [**kwargs])</insert><dialog title="Insert warning">warning(%0, %1, %2)</dialog><info title="Info window"></info></function>

17404

17405

17406

<description>Logs a message with level ERROR on the root logger.

17407

The arguments are interpreted as for debug().</description>

17408

<param name="msg" optional="0">msg</param><param name="*args" optional="1">*args</param><param name="**kwargs" optional="1">**kwargs</param>

17409

<insert>error(msg, [*args], [**kwargs])</insert><dialog title="Insert error">error(%0, %1, %2)</dialog><info title="Info window"></info></function>

17410

17411

17412

<description>Logs a message with level CRITICAL on the root logger.

17413

The arguments are interpreted as for debug().</description>

17414

<param name="msg" optional="0">msg</param><param name="*args" optional="1">*args</param><param name="**kwargs" optional="1">**kwargs</param>

17415

<insert>critical(msg, [*args], [**kwargs])</insert><dialog title="Insert critical">critical(%0, %1, %2)</dialog><info title="Info window"></info></function>

17416

17417

17418

<description>Logs a message with level ERROR on the root logger.

17419

The arguments are interpreted as for debug(). Exception info

17420

is added to the logging message. This function should only be called

17421

from an exception handler.</description>

17422

17423

<insert>exception(msg, [*args])</insert><dialog title="Insert exception">exception(%0, %1)</dialog><info title="Info window"></info></function>

17424

17425

17426

<description>Provides an overriding level lvl for all loggers which takes

17427

precedence over the logger's own level. When the need arises to

17428

temporarily throttle logging output down across the whole application,

17429

this function can be useful.</description>

17430

<param name="lvllvl" optional="0">lvllvl</param>

17431

<insert>disable(lvllvl)</insert><dialog title="Insert disable">disable(%0)</dialog><info title="Info window"></info></function>

17432

17433

17434

<description>Associates level lvl with text levelName in an internal

17435

dictionary, which is used to map numeric levels to a textual

17436

representation, for example when a Formatter formats a message.

17437

This function can also be used to define your own levels. The only

17438

constraints are that all levels used must be registered using this

17439

function, levels should be positive integers and they should increase

17440

in increasing order of severity.</description>

17441

<param name="lvl" optional="0">lvl</param><param name="levelName levelName" optional="0">levelName levelName</param>

17442

<insert>addLevelName(lvl, levelName levelName)</insert><dialog title="Insert addLevelName">addLevelName(%0, %1)</dialog><info title="Info window"></info></function>

17443

17444

17445

<description>Returns the textual representation of logging level lvl. If the

17446

level is one of the predefined levels CRITICAL,

17447

ERROR, WARNING, INFO or DEBUG

17448

then you get the corresponding string. If you have associated levels

17449

with names using addLevelName() then the name you have associated

17450

with lvl is returned. Otherwise, the string "Level " % lvl is

17451

returned.</description>

17452

<param name="lvllvl" optional="0">lvllvl</param>

17453

<insert>getLevelName(lvllvl)</insert><dialog title="Insert getLevelName">getLevelName(%0)</dialog><info title="Info window"></info></function>

17454

17455

17456

<description>Creates and returns a new LogRecord instance whose attributes are

17457

defined by attrdict. This function is useful for taking a pickled

17458

LogRecord attribute dictionary, sent over a socket, and reconstituting

17459

it as a LogRecord instance at the receiving end.</description>

17460

<param name="attrdictattrdict" optional="0">attrdictattrdict</param>

17461

<insert>makeLogRecord(attrdictattrdict)</insert><dialog title="Insert makeLogRecord">makeLogRecord(%0)</dialog><info title="Info window"></info></function>

17462

17463

17464

<description>Does basic configuration for the logging system by creating a

17465

StreamHandler with a default Formatter and adding it to

17466

the root logger. The functions debug(), info(),

17467

warning(), error() and critical() will call

17468

basicConfig() automatically if no handlers are defined for the

17469

root logger.</description>

17470

17471

<insert>basicConfig()</insert><dialog title="Insert basicConfig">basicConfig()</dialog><info title="Info window"></info></function>

17472

17473

17474

<description>Informs the logging system to perform an orderly shutdown by flushing and

17475

closing all handlers.</description>

17476

17477

<insert>shutdown()</insert><dialog title="Insert shutdown">shutdown()</dialog><info title="Info window"></info></function>

17478

17479

17480

<description>Tells the logging system to use the class klass when instantiating a

17481

logger. The class should define __init__() such that only a name

17482

argument is required, and the __init__() should call

17483

Logger.__init__(). This function is typically called before any

17484

loggers are instantiated by applications which need to use custom logger

17485

behavior.</description>

17486

<param name="klassklass" optional="0">klassklass</param>

17487

<insert>setLoggerClass(klassklass)</insert><dialog title="Insert setLoggerClass">setLoggerClass(%0)</dialog><info title="Info window"></info></function>

17488

17489

17490

<description>Loggers have the following attributes and methods. Note that Loggers are

17491

never instantiated directly, but always through the module-level function

17492

logging.getLogger(name).

17493

{propagate}

17494

If this evaluates to false, logging messages are not passed by this

17495

logger or by child loggers to higher level (ancestor) loggers. The

17496

constructor sets this attribute to 1.

17497

</description>

17498

17499

<description>Sets the threshold for this logger to lvl. Logging messages

17500

which are less severe than lvl will be ignored. When a logger is

17501

created, the level is set to NOTSET (which causes all messages

17502

to be processed in the root logger, or delegation to the parent in non-root

17503

loggers).</description>

17504

<param name="lvllvl" optional="0">lvllvl</param>

17505

<insert>setLevel(lvllvl)</insert><dialog title="Insert setLevel">setLevel(%0)</dialog><info title="Info window"></info></function>

17506

17507

17508

<description>Indicates if a message of severity lvl would be processed by

17509

this logger. This method checks first the module-level level set by

17510

logging.disable(lvl) and then the logger's effective level as

17511

determined by getEffectiveLevel().</description>

17512

<param name="lvllvl" optional="0">lvllvl</param>

17513

<insert>isEnabledFor(lvllvl)</insert><dialog title="Insert isEnabledFor">isEnabledFor(%0)</dialog><info title="Info window"></info></function>

17514

17515

17516

<description>Indicates the effective level for this logger. If a value other than

17517

NOTSET has been set using setLevel(), it is returned.

17518

Otherwise, the hierarchy is traversed towards the root until a value

17519

other than NOTSET is found, and that value is returned.</description>

17520

17521

<insert>getEffectiveLevel()</insert><dialog title="Insert getEffectiveLevel">getEffectiveLevel()</dialog><info title="Info window"></info></function>

17522

17523

17524

<description>Logs a message with level DEBUG on this logger.

17525

The msg is the message format string, and the args are the

17526

arguments which are merged into msg. The only keyword argument in

17527

kwargs which is inspected is exc_info which, if it does not

17528

evaluate as false, causes exception information (via a call to

17529

sys.exc_info()) to be added to the logging message.</description>

17530

<param name="msg" optional="0">msg</param><param name="*args" optional="1">*args</param><param name="**kwargs" optional="1">**kwargs</param>

17531

<insert>debug(msg, [*args], [**kwargs])</insert><dialog title="Insert debug">debug(%0, %1, %2)</dialog><info title="Info window"></info></function>

17532

17533

17534

<description>Logs a message with level INFO on this logger.

17535

The arguments are interpreted as for debug().</description>

17536

<param name="msg" optional="0">msg</param><param name="*args" optional="1">*args</param><param name="**kwargs" optional="1">**kwargs</param>

17537

<insert>info(msg, [*args], [**kwargs])</insert><dialog title="Insert info">info(%0, %1, %2)</dialog><info title="Info window"></info></function>

17538

17539

17540

<description>Logs a message with level WARNING on this logger.

17541

The arguments are interpreted as for debug().</description>

17542

<param name="msg" optional="0">msg</param><param name="*args" optional="1">*args</param><param name="**kwargs" optional="1">**kwargs</param>

17543

<insert>warning(msg, [*args], [**kwargs])</insert><dialog title="Insert warning">warning(%0, %1, %2)</dialog><info title="Info window"></info></function>

17544

17545

17546

<description>Logs a message with level ERROR on this logger.

17547

The arguments are interpreted as for debug().</description>

17548

<param name="msg" optional="0">msg</param><param name="*args" optional="1">*args</param><param name="**kwargs" optional="1">**kwargs</param>

17549

<insert>error(msg, [*args], [**kwargs])</insert><dialog title="Insert error">error(%0, %1, %2)</dialog><info title="Info window"></info></function>

17550

17551

17552

<description>Logs a message with level CRITICAL on this logger.

17553

The arguments are interpreted as for debug().</description>

17554

<param name="msg" optional="0">msg</param><param name="*args" optional="1">*args</param><param name="**kwargs" optional="1">**kwargs</param>

17555

<insert>critical(msg, [*args], [**kwargs])</insert><dialog title="Insert critical">critical(%0, %1, %2)</dialog><info title="Info window"></info></function>

17556

17557

17558

<description>Logs a message with level lvl on this logger.

17559

The other arguments are interpreted as for debug().</description>

17560

<param name="lvl" optional="0">lvl</param><param name="msg" optional="0">msg</param><param name="*args" optional="1">*args</param><param name="**kwargs" optional="1">**kwargs</param>

17561

<insert>log(lvl, msg, [*args], [**kwargs])</insert><dialog title="Insert log">log(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

17562

17563

17564

<description>Logs a message with level ERROR on this logger.

17565

The arguments are interpreted as for debug(). Exception info

17566

is added to the logging message. This method should only be called

17567

from an exception handler.</description>

17568

17569

<insert>exception(msg, [*args])</insert><dialog title="Insert exception">exception(%0, %1)</dialog><info title="Info window"></info></function>

17570

17571

17572

<description>Adds the specified filter filt to this logger.</description>

17573

<param name="filtfilt" optional="0">filtfilt</param>

17574

<insert>addFilter(filtfilt)</insert><dialog title="Insert addFilter">addFilter(%0)</dialog><info title="Info window"></info></function>

17575

17576

17577

<description>Removes the specified filter filt from this logger.</description>

17578

<param name="filtfilt" optional="0">filtfilt</param>

17579

<insert>removeFilter(filtfilt)</insert><dialog title="Insert removeFilter">removeFilter(%0)</dialog><info title="Info window"></info></function>

17580

17581

17582

<description>Applies this logger's filters to the record and returns a true value if

17583

the record is to be processed.</description>

17584

<param name="recordrecord" optional="0">recordrecord</param>

17585

<insert>filter(recordrecord)</insert><dialog title="Insert filter">filter(%0)</dialog><info title="Info window"></info></function>

17586

17587

17588

<description>Adds the specified handler hdlr to this logger.</description>

17589

<param name="hdlrhdlr" optional="0">hdlrhdlr</param>

17590

<insert>addHandler(hdlrhdlr)</insert><dialog title="Insert addHandler">addHandler(%0)</dialog><info title="Info window"></info></function>

17591

17592

17593

<description>Removes the specified handler hdlr from this logger.</description>

17594

<param name="hdlrhdlr" optional="0">hdlrhdlr</param>

17595

<insert>removeHandler(hdlrhdlr)</insert><dialog title="Insert removeHandler">removeHandler(%0)</dialog><info title="Info window"></info></function>

17596

17597

17598

<description>Finds the caller's source filename and line number. Returns the filename

17599

and line number as a 2-element tuple.</description>

17600

17601

<insert>findCaller()</insert><dialog title="Insert findCaller">findCaller()</dialog><info title="Info window"></info></function>

17602

17603

17604

<description>Handles a record by passing it to all handlers associated with this logger

17605

and its ancestors (until a false value of propagate is found).

17606

This method is used for unpickled records received from a socket, as well

17607

as those created locally. Logger-level filtering is applied using

17608

filter().</description>

17609

<param name="recordrecord" optional="0">recordrecord</param>

17610

<insert>handle(recordrecord)</insert><dialog title="Insert handle">handle(%0)</dialog><info title="Info window"></info></function>

17611

17612

17613

<description>This is a factory method which can be overridden in subclasses to create

17614

specialized LogRecord instances.</description>

17615

17616

<insert>makeRecord(name, lvl, fn, lno, msg, args, exc_info exc_info)</insert><dialog title="Insert makeRecord">makeRecord(%0, %1, %2, %3, %4, %5, %6)</dialog><info title="Info window"></info></function>

17617

17618

</group>

17619

17620

<description>Handlers have the following attributes and methods. Note that

17621

Handler is never instantiated directly; this class acts as a

17622

base for more useful subclasses. However, the __init__()

17623

method in subclasses needs to call Handler.__init__().

17624

</description>

17625

17626

<description>Initializes the Handler instance by setting its level, setting

17627

the list of filters to the empty list and creating a lock (using

17628

createLock()) for serializing access to an I/O mechanism.</description>

17629

<param name="level" optional="0" default="NOTSET">level</param>

17630

<insert>__init__(level)</insert><dialog title="Insert __init__">__init__(%0)</dialog><info title="Info window"></info></function>

17631

17632

17633

<description>Initializes a thread lock which can be used to serialize access to

17634

underlying I/O functionality which may not be threadsafe.</description>

17635

17636

<insert>createLock()</insert><dialog title="Insert createLock">createLock()</dialog><info title="Info window"></info></function>

17637

17638

17639

<description>Acquires the thread lock created with createLock().</description>

17640

17641

<insert>acquire()</insert><dialog title="Insert acquire">acquire()</dialog><info title="Info window"></info></function>

17642

17643

17644

<description>Releases the thread lock acquired with acquire().</description>

17645

17646

<insert>release()</insert><dialog title="Insert release">release()</dialog><info title="Info window"></info></function>

17647

17648

17649

<description>Sets the threshold for this handler to lvl. Logging messages which are

17650

less severe than lvl will be ignored. When a handler is created, the

17651

level is set to NOTSET (which causes all messages to be processed).</description>

17652

<param name="lvllvl" optional="0">lvllvl</param>

17653

<insert>setLevel(lvllvl)</insert><dialog title="Insert setLevel">setLevel(%0)</dialog><info title="Info window"></info></function>

17654

17655

17656

<description>Sets the Formatter for this handler to form.</description>

17657

<param name="formform" optional="0">formform</param>

17658

<insert>setFormatter(formform)</insert><dialog title="Insert setFormatter">setFormatter(%0)</dialog><info title="Info window"></info></function>

17659

17660

17661

<description>Adds the specified filter filt to this handler.</description>

17662

<param name="filtfilt" optional="0">filtfilt</param>

17663

<insert>addFilter(filtfilt)</insert><dialog title="Insert addFilter">addFilter(%0)</dialog><info title="Info window"></info></function>

17664

17665

17666

<description>Removes the specified filter filt from this handler.</description>

17667

<param name="filtfilt" optional="0">filtfilt</param>

17668

<insert>removeFilter(filtfilt)</insert><dialog title="Insert removeFilter">removeFilter(%0)</dialog><info title="Info window"></info></function>

17669

17670

17671

<description>Applies this handler's filters to the record and returns a true value if

17672

the record is to be processed.</description>

17673

<param name="recordrecord" optional="0">recordrecord</param>

17674

<insert>filter(recordrecord)</insert><dialog title="Insert filter">filter(%0)</dialog><info title="Info window"></info></function>

17675

17676

17677

<description>Ensure all logging output has been flushed. This version does

17678

nothing and is intended to be implemented by subclasses.</description>

17679

17680

<insert>flush()</insert><dialog title="Insert flush">flush()</dialog><info title="Info window"></info></function>

17681

17682

17683

<description>Tidy up any resources used by the handler. This version does

17684

nothing and is intended to be implemented by subclasses.</description>

17685

17686

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

17687

17688

17689

<description>Conditionally emits the specified logging record, depending on

17690

filters which may have been added to the handler. Wraps the actual

17691

emission of the record with acquisition/release of the I/O thread

17692

lock.</description>

17693

<param name="recordrecord" optional="0">recordrecord</param>

17694

<insert>handle(recordrecord)</insert><dialog title="Insert handle">handle(%0)</dialog><info title="Info window"></info></function>

17695

17696

17697

<description>This method should be called from handlers when an exception is

17698

encountered during an emit() call. By default it does nothing,

17699

which means that exceptions get silently ignored. This is what is

17700

mostly wanted for a logging system - most users will not care

17701

about errors in the logging system, they are more interested in

17702

application errors. You could, however, replace this with a custom

17703

handler if you wish.</description>

17704

17705

<insert>handleError()</insert><dialog title="Insert handleError">handleError()</dialog><info title="Info window"></info></function>

17706

17707

17708

<description>Do formatting for a record - if a formatter is set, use it.

17709

Otherwise, use the default formatter for the module.</description>

17710

<param name="recordrecord" optional="0">recordrecord</param>

17711

<insert>format(recordrecord)</insert><dialog title="Insert format">format(%0)</dialog><info title="Info window"></info></function>

17712

17713

17714

<description>Do whatever it takes to actually log the specified logging record.

17715

This version is intended to be implemented by subclasses and so

17716

raises a NotImplementedError.</description>

17717

<param name="recordrecord" optional="0">recordrecord</param>

17718

<insert>emit(recordrecord)</insert><dialog title="Insert emit">emit(%0)</dialog><info title="Info window"></info></function>

17719

17720

17721

<description>Returns a new instance of the StreamHandler class. If strm is

17722

specified, the instance will use it for logging output; otherwise,

17723

sys.stderr will be used.</description>

17724

17725

<insert>StreamHandler(strm)</insert><dialog title="Insert StreamHandler">StreamHandler(%0)</dialog><info title="Info window"></info></function>

17726

17727

17728

<description>If a formatter is specified, it is used to format the record.

17729

The record is then written to the stream with a trailing newline.

17730

If exception information is present, it is formatted using

17731

traceback.print_exception() and appended to the stream.</description>

17732

<param name="recordrecord" optional="0">recordrecord</param>

17733

<insert>emit(recordrecord)</insert><dialog title="Insert emit">emit(%0)</dialog><info title="Info window"></info></function>

17734

17735

17736

<description>Flushes the stream by calling its flush() method. Note that

17737

the close() method is inherited from Handler and

17738

so does nothing, so an explicit flush() call may be needed

17739

at times.</description>

17740

17741

<insert>flush()</insert><dialog title="Insert flush">flush()</dialog><info title="Info window"></info></function>

17742

17743

17744

<description>Returns a new instance of the FileHandler class. The specified

17745

file is opened and used as the stream for logging. If mode is

17746

not specified, 'a' is used. By default, the file grows

17747

indefinitely.</description>

17748

<param name="filename" optional="0">filename</param><param name="mode" optional="1">mode</param>

17749

<insert>FileHandler(filename, [mode])</insert><dialog title="Insert FileHandler">FileHandler(%0, %1)</dialog><info title="Info window"></info></function>

17750

17751

17752

<description>Closes the file.</description>

17753

17754

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

17755

17756

17757

<description>Outputs the record to the file.</description>

17758

<param name="recordrecord" optional="0">recordrecord</param>

17759

<insert>emit(recordrecord)</insert><dialog title="Insert emit">emit(%0)</dialog><info title="Info window"></info></function>

17760

17761

17762

<description>Returns a new instance of the RotatingFileHandler class. The

17763

specified file is opened and used as the stream for logging. If

17764

mode is not specified, 'a' is used. By default, the

17765

file grows indefinitely. You can use the maxBytes and

17766

backupCount values to allow the file to rollover at a

17767

predetermined size. When the size is about to be exceeded, the file is

17768

closed and a new file is silently opened for output. Rollover occurs

17769

whenever the current log file is nearly maxBytes in length; if

17770

maxBytes is zero, rollover never occurs. If backupCount

17771

is non-zero, the system will save old log files by appending the

17772

extensions ".1", ".2" etc., to the filename. For example, with

17773

a backupCount of 5 and a base file name of

17774

app.log, you would get app.log,

17775

app.log.1, app.log.2, up to app.log.5. The file being

17776

written to is always app.log. When this file is filled, it is

17777

closed and renamed to app.log.1, and if files app.log.1,

17778

app.log.2, etc. exist, then they are renamed to app.log.2,

17779

app.log.3 etc. respectively.</description>

17780

<param name="filename" optional="0">filename</param><param name="mode" optional="1">mode</param><param name="maxBytes" optional="1">maxBytes</param><param name="backupCount" optional="1">backupCount</param>

17781

<insert>RotatingFileHandler(filename, [mode], [maxBytes], [backupCount])</insert><dialog title="Insert RotatingFileHandler">RotatingFileHandler(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

17782

17783

17784

<description>Does a rollover, as described above.</description>

17785

17786

<insert>doRollover()</insert><dialog title="Insert doRollover">doRollover()</dialog><info title="Info window"></info></function>

17787

17788

17789

<description>Outputs the record to the file, catering for rollover as described

17790

in setRollover().</description>

17791

<param name="recordrecord" optional="0">recordrecord</param>

17792

<insert>emit(recordrecord)</insert><dialog title="Insert emit">emit(%0)</dialog><info title="Info window"></info></function>

17793

17794

17795

<description>Returns a new instance of the SocketHandler class intended to

17796

communicate with a remote machine whose address is given by host

17797

and port.</description>

17798

17799

<insert>SocketHandler(host, port port)</insert><dialog title="Insert SocketHandler">SocketHandler(%0, %1)</dialog><info title="Info window"></info></function>

17800

17801

17802

<description>Closes the socket.</description>

17803

17804

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

17805

17806

17807

17808

17809

<insert>handleError()</insert><dialog title="Insert handleError">handleError()</dialog><info title="Info window"></info></function>

17810

17811

17812

<description>Pickles the record's attribute dictionary and writes it to the socket in

17813

binary format. If there is an error with the socket, silently drops the

17814

packet. If the connection was previously lost, re-establishes the connection.

17815

To unpickle the record at the receiving end into a LogRecord, use the

17816

makeLogRecord function.</description>

17817

17818

17819

17820

17821

<description>Handles an error which has occurred during emit(). The

17822

most likely cause is a lost connection. Closes the socket so that

17823

we can retry on the next event.</description>

17824

17825

<insert>handleError()</insert><dialog title="Insert handleError">handleError()</dialog><info title="Info window"></info></function>

17826

17827

17828

<description>This is a factory method which allows subclasses to define the precise

17829

type of socket they want. The default implementation creates a TCP

17830

socket (socket.SOCK_STREAM).</description>

17831

17832

<insert>makeSocket()</insert><dialog title="Insert makeSocket">makeSocket()</dialog><info title="Info window"></info></function>

17833

17834

17835

<description>Pickles the record's attribute dictionary in binary format with a length

17836

prefix, and returns it ready for transmission across the socket.</description>

17837

<param name="recordrecord" optional="0">recordrecord</param>

17838

<insert>makePickle(recordrecord)</insert><dialog title="Insert makePickle">makePickle(%0)</dialog><info title="Info window"></info></function>

17839

17840

17841

<description>Send a pickled string packet to the socket. This function allows

17842

for partial sends which can happen when the network is busy.</description>

17843

<param name="packetpacket" optional="0">packetpacket</param>

17844

<insert>send(packetpacket)</insert><dialog title="Insert send">send(%0)</dialog><info title="Info window"></info></function>

17845

17846

17847

<description>Returns a new instance of the DatagramHandler class intended to

17848

communicate with a remote machine whose address is given by host

17849

and port.</description>

17850

17851

<insert>DatagramHandler(host, port port)</insert><dialog title="Insert DatagramHandler">DatagramHandler(%0, %1)</dialog><info title="Info window"></info></function>

17852

17853

17854

<description>Pickles the record's attribute dictionary and writes it to the socket in

17855

binary format. If there is an error with the socket, silently drops the

17856

packet.

17857

To unpickle the record at the receiving end into a LogRecord, use the

17858

makeLogRecord function.</description>

17859

17860

17861

17862

17863

<description>The factory method of SocketHandler is here overridden to create

17864

a UDP socket (socket.SOCK_DGRAM).</description>

17865

17866

<insert>makeSocket()</insert><dialog title="Insert makeSocket">makeSocket()</dialog><info title="Info window"></info></function>

17867

17868

17869

<description>Send a pickled string to a socket.</description>

17870

17871

17872

17873

17874

<description>Returns a new instance of the SysLogHandler class intended to

17875

communicate with a remote machine whose address is given by

17876

address in the form of a (host, port)

17877

tuple. If address is not specified, ('localhost', 514) is

17878

used. The address is used to open a UDP socket. If facility is

17879

not specified, LOG_USER is used.</description>

17880

<param name="address" optional="0">address</param><param name="facility" optional="1">facility</param>

17881

<insert>SysLogHandler(address, [facility])</insert><dialog title="Insert SysLogHandler">SysLogHandler(%0, %1)</dialog><info title="Info window"></info></function>

17882

17883

17884

<description>Closes the socket to the remote host.</description>

17885

17886

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

17887

17888

17889

<description>The record is formatted, and then sent to the syslog server. If

17890

exception information is present, it is not sent to the server.</description>

17891

<param name="recordrecord" optional="0">recordrecord</param>

17892

<insert>emit(recordrecord)</insert><dialog title="Insert emit">emit(%0)</dialog><info title="Info window"></info></function>

17893

17894

17895

<description>Encodes the facility and priority into an integer. You can pass in strings

17896

or integers - if strings are passed, internal mapping dictionaries are used

17897

to convert them to integers.</description>

17898

<param name="facility" optional="0">facility</param><param name="priority priority" optional="0">priority priority</param>

17899

<insert>encodePriority(facility, priority priority)</insert><dialog title="Insert encodePriority">encodePriority(%0, %1)</dialog><info title="Info window"></info></function>

17900

17901

17902

<description>Returns a new instance of the NTEventLogHandler class. The

17903

appname is used to define the application name as it appears in the

17904

event log. An appropriate registry entry is created using this name.

17905

The dllname should give the fully qualified pathname of a .dll or .exe

17906

which contains message definitions to hold in the log (if not specified,

17907

'win32service.pyd' is used - this is installed with the Win32

17908

extensions and contains some basic placeholder message definitions.

17909

Note that use of these placeholders will make your event logs big, as the

17910

entire message source is held in the log. If you want slimmer logs, you have

17911

to pass in the name of your own .dll or .exe which contains the message

17912

definitions you want to use in the event log). The logtype is one of

17913

'Application', 'System' or 'Security', and

17914

defaults to 'Application'.</description>

17915

<param name="appname" optional="0">appname</param><param name="dllname" optional="1">dllname</param><param name="logtype" optional="1">logtype</param>

17916

<insert>NTEventLogHandler(appname, [dllname], [logtype])</insert><dialog title="Insert NTEventLogHandler">NTEventLogHandler(%0, %1, %2)</dialog><info title="Info window"></info></function>

17917

17918

17919

<description>At this point, you can remove the application name from the registry as a

17920

source of event log entries. However, if you do this, you will not be able

17921

to see the events as you intended in the Event Log Viewer - it needs to be

17922

able to access the registry to get the .dll name. The current version does

17923

not do this (in fact it doesn't do anything).</description>

17924

17925

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

17926

17927

17928

<description>Determines the message ID, event category and event type, and then logs the

17929

message in the NT event log.</description>

17930

<param name="recordrecord" optional="0">recordrecord</param>

17931

<insert>emit(recordrecord)</insert><dialog title="Insert emit">emit(%0)</dialog><info title="Info window"></info></function>

17932

17933

17934

<description>Returns the event category for the record. Override this if you

17935

want to specify your own categories. This version returns 0.</description>

17936

<param name="recordrecord" optional="0">recordrecord</param>

17937

<insert>getEventCategory(recordrecord)</insert><dialog title="Insert getEventCategory">getEventCategory(%0)</dialog><info title="Info window"></info></function>

17938

17939

17940

<description>Returns the event type for the record. Override this if you want

17941

to specify your own types. This version does a mapping using the

17942

handler's typemap attribute, which is set up in __init__()

17943

to a dictionary which contains mappings for DEBUG,

17944

INFO, WARNING, ERROR and

17945

CRITICAL. If you are using your own levels, you will either need

17946

to override this method or place a suitable dictionary in the

17947

handler's typemap attribute.</description>

17948

<param name="recordrecord" optional="0">recordrecord</param>

17949

<insert>getEventType(recordrecord)</insert><dialog title="Insert getEventType">getEventType(%0)</dialog><info title="Info window"></info></function>

17950

17951

17952

<description>Returns the message ID for the record. If you are using your

17953

own messages, you could do this by having the msg passed to the

17954

logger being an ID rather than a format string. Then, in here,

17955

you could use a dictionary lookup to get the message ID. This

17956

version returns 1, which is the base message ID in

17957

win32service.pyd.</description>

17958

<param name="recordrecord" optional="0">recordrecord</param>

17959

<insert>getMessageID(recordrecord)</insert><dialog title="Insert getMessageID">getMessageID(%0)</dialog><info title="Info window"></info></function>

17960

17961

17962

<description>Returns a new instance of the SMTPHandler class. The

17963

instance is initialized with the from and to addresses and subject

17964

line of the email. The toaddrs should be a list of strings without

17965

domain names (That's what the mailhost is for). To specify a

17966

non-standard SMTP port, use the (host, port) tuple format for the

17967

mailhost argument. If you use a string, the standard SMTP port

17968

is used.</description>

17969

<param name="mailhost" optional="0">mailhost</param><param name="fromaddr" optional="0">fromaddr</param><param name="toaddrs" optional="0">toaddrs</param><param name="subject subject" optional="0">subject subject</param>

17970

<insert>SMTPHandler(mailhost, fromaddr, toaddrs, subject subject)</insert><dialog title="Insert SMTPHandler">SMTPHandler(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

17971

17972

17973

<description>Formats the record and sends it to the specified addressees.</description>

17974

<param name="recordrecord" optional="0">recordrecord</param>

17975

<insert>emit(recordrecord)</insert><dialog title="Insert emit">emit(%0)</dialog><info title="Info window"></info></function>

17976

17977

17978

<description>If you want to specify a subject line which is record-dependent,

17979

override this method.</description>

17980

<param name="recordrecord" optional="0">recordrecord</param>

17981

<insert>getSubject(recordrecord)</insert><dialog title="Insert getSubject">getSubject(%0)</dialog><info title="Info window"></info></function>

17982

17983

17984

<description>Initializes the handler with a buffer of the specified capacity.</description>

17985

<param name="capacitycapacity" optional="0">capacitycapacity</param>

17986

<insert>BufferingHandler(capacitycapacity)</insert><dialog title="Insert BufferingHandler">BufferingHandler(%0)</dialog><info title="Info window"></info></function>

17987

17988

17989

<description>Appends the record to the buffer. If shouldFlush() returns true,

17990

calls flush() to process the buffer.</description>

17991

<param name="recordrecord" optional="0">recordrecord</param>

17992

<insert>emit(recordrecord)</insert><dialog title="Insert emit">emit(%0)</dialog><info title="Info window"></info></function>

17993

17994

17995

<description>You can override this to implement custom flushing behavior. This version

17996

just zaps the buffer to empty.</description>

17997

17998

<insert>flush()</insert><dialog title="Insert flush">flush()</dialog><info title="Info window"></info></function>

17999

18000

18001

<description>Returns true if the buffer is up to capacity. This method can be

18002

overridden to implement custom flushing strategies.</description>

18003

<param name="recordrecord" optional="0">recordrecord</param>

18004

<insert>shouldFlush(recordrecord)</insert><dialog title="Insert shouldFlush">shouldFlush(%0)</dialog><info title="Info window"></info></function>

18005

18006

18007

<description>Returns a new instance of the MemoryHandler class. The

18008

instance is initialized with a buffer size of capacity. If

18009

flushLevel is not specified, ERROR is used. If no

18010

target is specified, the target will need to be set using

18011

setTarget() before this handler does anything useful.</description>

18012

<param name="capacity" optional="0">capacity</param><param name="flushLevel" optional="1">flushLevel</param><param name="target" optional="1">target</param>

18013

<insert>MemoryHandler(capacity, [flushLevel], [target])</insert><dialog title="Insert MemoryHandler">MemoryHandler(%0, %1, %2)</dialog><info title="Info window"></info></function>

18014

18015

18016

<description>Calls flush(), sets the target to None and

18017

clears the buffer.</description>

18018

18019

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

18020

18021

18022

<description>For a MemoryHandler, flushing means just sending the buffered

18023

records to the target, if there is one. Override if you want

18024

different behavior.</description>

18025

18026

<insert>flush()</insert><dialog title="Insert flush">flush()</dialog><info title="Info window"></info></function>

18027

18028

18029

<description>Sets the target handler for this handler.</description>

18030

<param name="targettarget" optional="0">targettarget</param>

18031

<insert>setTarget(targettarget)</insert><dialog title="Insert setTarget">setTarget(%0)</dialog><info title="Info window"></info></function>

18032

18033

18034

<description>Checks for buffer full or a record at the flushLevel or higher.</description>

18035

<param name="recordrecord" optional="0">recordrecord</param>

18036

<insert>shouldFlush(recordrecord)</insert><dialog title="Insert shouldFlush">shouldFlush(%0)</dialog><info title="Info window"></info></function>

18037

18038

18039

<description>Returns a new instance of the HTTPHandler class. The

18040

instance is initialized with a host address, url and HTTP method.

18041

If no method is specified, GET is used.</description>

18042

<param name="host" optional="0">host</param><param name="url" optional="0">url</param><param name="method" optional="1">method</param>

18043

<insert>HTTPHandler(host, url, [method])</insert><dialog title="Insert HTTPHandler">HTTPHandler(%0, %1, %2)</dialog><info title="Info window"></info></function>

18044

18045

18046

<description>Sends the record to the Web server as an URL-encoded dictionary.</description>

18047

<param name="recordrecord" optional="0">recordrecord</param>

18048

<insert>emit(recordrecord)</insert><dialog title="Insert emit">emit(%0)</dialog><info title="Info window"></info></function>

18049

18050

</group>

18051

18052

<description>Formatters have the following attributes and methods. They are

18053

responsible for converting a LogRecord to (usually) a string

18054

which can be interpreted by either a human or an external system. The

18055

base

18056

Formatter allows a formatting string to be specified. If none is

18057

supplied, the default value of '%(message)s\ is used.

18058

A Formatter can be initialized with a format string which makes use of

18059

knowledge of the LogRecord attributes - such as the default value

18060

mentioned above making use of the fact that the user's message and

18061

arguments are pre-formatted into a LogRecord's message

18062

attribute. This format string contains standard python %-style

18063

mapping keys. See section typesseq-strings, ``String Formatting

18064

Operations,'' for more information on string formatting.

18065

Currently, the useful mapping keys in a LogRecord are:

18066

{l|l}{code}{Format}{Description}

18067

%(name)s {Name of the logger (logging channel).}

18068

%(levelno)s {Numeric logging level for the message

18069

(DEBUG, INFO,

18070

WARNING, ERROR,

18071

CRITICAL).}

18072

%(levelname)s{Text logging level for the message

18073

('DEBUG', 'INFO',

18074

'WARNING', 'ERROR',

18075

'CRITICAL').}

18076

%(pathname)s {Full pathname of the source file where the logging

18077

call was issued (if available).}

18078

%(filename)s {Filename portion of pathname.}

18079

%(module)s {Module (name portion of filename).}

18080

%(lineno)d {Source line number where the logging call was issued

18081

(if available).}

18082

%(created)f {Time when the LogRecord was created (as

18083

returned by time.time()).}

18084

%(asctime)s {Human-readable time when the LogRecord was created.

18085

By default this is of the form

18086

``2003-07-08 16:49:45,896'' (the numbers after the

18087

comma are millisecond portion of the time).}

18088

%(msecs)d {Millisecond portion of the time when the

18089

LogRecord was created.}

18090

%(thread)d {Thread ID (if available).}

18091

%(process)d {Process ID (if available).}

18092

%(message)s {The logged message, computed as msg % args.}

18093

</description>

18094

18095

<description>Returns a new instance of the Formatter class. The

18096

instance is initialized with a format string for the message as a whole,

18097

as well as a format string for the date/time portion of a message. If

18098

no fmt is specified, '%(message)s' is used. If no datefmt

18099

is specified, the ISO8601 date format is used.</description>

18100

<param name="fmt" optional="0">fmt</param><param name="datefmt" optional="1">datefmt</param>

18101

<insert>Formatter(fmt, [datefmt])</insert><dialog title="Insert Formatter">Formatter(%0, %1)</dialog><info title="Info window"></info></function>

18102

18103

18104

<description>The record's attribute dictionary is used as the operand to a

18105

string formatting operation. Returns the resulting string.

18106

Before formatting the dictionary, a couple of preparatory steps

18107

are carried out. The message attribute of the record is computed

18108

using msg % args. If the formatting string contains

18109

'(asctime)', formatTime() is called to format the

18110

event time. If there is exception information, it is formatted using

18111

formatException() and appended to the message.</description>

18112

<param name="recordrecord" optional="0">recordrecord</param>

18113

<insert>format(recordrecord)</insert><dialog title="Insert format">format(%0)</dialog><info title="Info window"></info></function>

18114

18115

18116

<description>This method should be called from format() by a formatter which

18117

wants to make use of a formatted time. This method can be overridden

18118

in formatters to provide for any specific requirement, but the

18119

basic behavior is as follows: if datefmt (a string) is specified,

18120

it is used with time.strftime() to format the creation time of the

18121

record. Otherwise, the ISO8601 format is used. The resulting

18122

string is returned.</description>

18123

<param name="record" optional="0">record</param><param name="datefmt" optional="1">datefmt</param>

18124

<insert>formatTime(record, [datefmt])</insert><dialog title="Insert formatTime">formatTime(%0, %1)</dialog><info title="Info window"></info></function>

18125

18126

18127

<description>Formats the specified exception information (a standard exception tuple

18128

as returned by sys.exc_info()) as a string. This default

18129

implementation just uses traceback.print_exception().

18130

The resulting string is returned.</description>

18131

<param name="exc_infoexc_info" optional="0">exc_infoexc_info</param>

18132

<insert>formatException(exc_infoexc_info)</insert><dialog title="Insert formatException">formatException(%0)</dialog><info title="Info window"></info></function>

18133

18134

</group>

18135

18136

<description>Filters can be used by Handlers and Loggers for

18137

more sophisticated filtering than is provided by levels. The base filter

18138

class only allows events which are below a certain point in the logger

18139

hierarchy. For example, a filter initialized with "A.B" will allow events

18140

logged by loggers "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB",

18141

"B.A.B" etc. If initialized with the empty string, all events are passed.

18142

</description>

18143

18144

<description>Returns an instance of the Filter class. If name is specified,

18145

it names a logger which, together with its children, will have its events

18146

allowed through the filter. If no name is specified, allows every event.</description>

18147

18148

<insert>Filter(name)</insert><dialog title="Insert Filter">Filter(%0)</dialog><info title="Info window"></info></function>

18149

18150

18151

<description>Is the specified record to be logged? Returns zero for no, nonzero for

18152

yes. If deemed appropriate, the record may be modified in-place by this

18153

method.</description>

18154

<param name="recordrecord" optional="0">recordrecord</param>

18155

<insert>filter(recordrecord)</insert><dialog title="Insert filter">filter(%0)</dialog><info title="Info window"></info></function>

18156

18157

</group>

18158

18159

<description>LogRecord instances are created every time something is logged. They

18160

contain all the information pertinent to the event being logged. The

18161

main information passed in is in msg and args, which are combined

18162

using msg % args to create the message field of the record. The record

18163

also includes information such as when the record was created, the

18164

source line where the logging call was made, and any exception

18165

information to be logged.

18166

LogRecord has no methods; it's just a repository for information about the

18167

logging event. The only reason it's a class rather than a dictionary is to

18168

facilitate extension.

18169

</description>

18170

18171

<description>Returns an instance of LogRecord initialized with interesting

18172

information. The name is the logger name; lvl is the

18173

numeric level; pathname is the absolute pathname of the source

18174

file in which the logging call was made; lineno is the line

18175

number in that file where the logging call is found; msg is the

18176

user-supplied message (a format string); args is the tuple

18177

which, together with msg, makes up the user message; and

18178

exc_info is the exception tuple obtained by calling

18179

sys.exc_info() (or None, if no exception information

18180

is available).</description>

18181

<param name="name" optional="0">name</param><param name="lvl" optional="0">lvl</param><param name="pathname" optional="0">pathname</param><param name="lineno" optional="0">lineno</param><param name="msg" optional="0">msg</param><param name="args" optional="0">args</param><param name="exc_info

18182

exc_info" optional="0">exc_info

18183

exc_info</param>

18184

<insert>LogRecord(name, lvl, pathname, lineno, msg, args, exc_info

18185

exc_info)</insert><dialog title="Insert LogRecord">LogRecord(%0, %1, %2, %3, %4, %5, %6)</dialog><info title="Info window"></info></function>

18186

18187

</group>

18188

18189

<description>The logging module is intended to be thread-safe without any special work

18190

needing to be done by its clients. It achieves this though using threading

18191

locks; there is one lock to serialize access to the module's shared data,

18192

and each handler also creates a lock to serialize access to its underlying

18193

I/O.

18194

</description>

18195

</group>

18196

18197

<description>Configuration functions

18198

The following functions allow the logging module to be

18199

configured. Before they can be used, you must import

18200

logging.config. Their use is optional --- you can configure

18201

the logging module entirely by making calls to the main API (defined

18202

in logging itself) and defining handlers which are declared

18203

either in logging or logging.handlers.

18204

</description>

18205

18206

<description>Reads the logging configuration from a ConfigParser-format file named

18207

fname. This function can be called several times from an application,

18208

allowing an end user the ability to select from various pre-canned

18209

configurations (if the developer provides a mechanism to present the

18210

choices and load the chosen configuration). Defaults to be passed to

18211

ConfigParser can be specified in the defaults argument.</description>

18212

<param name="fname" optional="0">fname</param><param name="defaults" optional="1">defaults</param>

18213

<insert>fileConfig(fname, [defaults])</insert><dialog title="Insert fileConfig">fileConfig(%0, %1)</dialog><info title="Info window"></info></function>

18214

18215

18216

<description>Starts up a socket server on the specified port, and listens for new

18217

configurations. If no port is specified, the module's default

18218

DEFAULT_LOGGING_CONFIG_PORT is used. Logging configurations

18219

will be sent as a file suitable for processing by fileConfig().

18220

Returns a Thread instance on which you can call start()

18221

to start the server, and which you can join() when appropriate.

18222

To stop the server, call stopListening().</description>

18223

18224

<insert>listen(port)</insert><dialog title="Insert listen">listen(%0)</dialog><info title="Info window"></info></function>

18225

18226

18227

<description>Stops the listening server which was created with a call to

18228

listen(). This is typically called before calling join()

18229

on the return value from listen().</description>

18230

18231

<insert>stopListening()</insert><dialog title="Insert stopListening">stopListening()</dialog><info title="Info window"></info></function>

18232

18233

</group>

18234

18235

</group>

18236

</group>

18237

18238

<description>Retrieves as much platform identifying data as possible.

18239

New in version 2.3

18240

Specific platforms listed alphabetically, with Linux included in the

18241

section.

18242

</description>

18243

18244

18245

<description>Queries the given executable (defaults to the Python interpreter

18246

binary) for various architecture informations.

18247

Returns a tuple (bits, linkage) which contain information about

18248

the bit architecture and the linkage format used for the

18249

executable. Both values are returned as strings.

18250

Values that cannot be determined are returned as given by the

18251

parameter presets. If bits is given as '', the

18252

sizeof(pointer)

18253

(or sizeof(long) on Python version < 1.5.2) is used as

18254

indicator for the supported pointer size.

18255

The function relies on the system's file command to do the

18256

actual work. This is available on most if not all platforms and some non- platforms and then only if the

18257

executable points to the Python interpreter. Reasonable defaults

18258

are used when the above needs are not met.</description>

18259

<param name="executable" optional="0" default="sys.executable">executable</param><param name="bits" optional="0" default="''">bits</param><param name="linkage" optional="0" default="'' linkage=''">linkage</param>

18260

<insert>architecture(executable, bits, linkage)</insert><dialog title="Insert architecture">architecture(%0, %1, %2)</dialog><info title="Info window"></info></function>

18261

18262

18263

<description>Returns the machine type, e.g. 'i386'.

18264

An empty string is returned if the value cannot be determined.</description>

18265

18266

<insert>machine()</insert><dialog title="Insert machine">machine()</dialog><info title="Info window"></info></function>

18267

18268

18269

<description>Returns the computer's network name (may not be fully qualified!).

18270

An empty string is returned if the value cannot be determined.</description>

18271

18272

18273

18274

18275

<description>Returns a single string identifying the underlying platform

18276

with as much useful information as possible.

18277

The output is intended to be human readable rather than

18278

machine parseable. It may look different on different platforms and

18279

this is intended.

18280

If aliased is true, the function will use aliases for various

18281

platforms that report system names which differ from their common

18282

names, for example SunOS will be reported as Solaris. The

18283

system_alias() function is used to implement this.

18284

Setting terse to true causes the function to return only the

18285

absolute minimum information needed to identify the platform.</description>

18286

<param name="aliased" optional="0" default="0">aliased</param><param name="terse" optional="0" default="0 terse=0">terse</param>

18287

<insert>platform(aliased, terse)</insert><dialog title="Insert platform">platform(%0, %1)</dialog><info title="Info window"></info></function>

18288

18289

18290

<description>Returns the (real) processor name, e.g. 'amdk6'.

18291

An empty string is returned if the value cannot be determined. Note

18292

that many platforms do not provide this information or simply return

18293

the same value as for machine(). NetBSD does this.</description>

18294

18295

<insert>processor()</insert><dialog title="Insert processor">processor()</dialog><info title="Info window"></info></function>

18296

18297

18298

<description>Returns a tuple (buildno, builddate) stating the

18299

Python build number and date as strings.</description>

18300

18301

<insert>python_build()</insert><dialog title="Insert python_build">python_build()</dialog><info title="Info window"></info></function>

18302

18303

18304

<description>Returns a string identifying the compiler used for compiling Python.</description>

18305

18306

<insert>python_compiler()</insert><dialog title="Insert python_compiler">python_compiler()</dialog><info title="Info window"></info></function>

18307

18308

18309

<description>Returns the Python version as string 'major.minor.patchlevel'

18310

Note that unlike the Python sys.version, the returned value

18311

will always include the patchlevel (it defaults to 0).</description>

18312

18313

<insert>python_version()</insert><dialog title="Insert python_version">python_version()</dialog><info title="Info window"></info></function>

18314

18315

18316

<description>Returns the Python version as tuple (major, minor,

18317

patchlevel) of strings.

18318

Note that unlike the Python sys.version, the returned value

18319

will always include the patchlevel (it defaults to '0').</description>

18320

18321

<insert>python_version_tuple()</insert><dialog title="Insert python_version_tuple">python_version_tuple()</dialog><info title="Info window"></info></function>

18322

18323

18324

<description>Returns the system's release, e.g. '2.2.0' or 'NT'

18325

An empty string is returned if the value cannot be determined.</description>

18326

18327

<insert>release()</insert><dialog title="Insert release">release()</dialog><info title="Info window"></info></function>

18328

18329

18330

<description>Returns the system/OS name, e.g. 'Linux', 'Windows',

18331

or 'Java'.

18332

An empty string is returned if the value cannot be determined.</description>

18333

18334

<insert>system()</insert><dialog title="Insert system">system()</dialog><info title="Info window"></info></function>

18335

18336

18337

<description>Returns (system, release, version) aliased

18338

to common marketing names used for some systems. It also does some

18339

reordering of the information in some cases where it would otherwise

18340

cause confusion.</description>

18341

<param name="system" optional="0">system</param><param name="release" optional="0">release</param><param name="version version" optional="0">version version</param>

18342

<insert>system_alias(system, release, version version)</insert><dialog title="Insert system_alias">system_alias(%0, %1, %2)</dialog><info title="Info window"></info></function>

18343

18344

18345

<description>Returns the system's release version, e.g. ' degas'.

18346

An empty string is returned if the value cannot be determined.</description>

18347

18348

<insert>version()</insert><dialog title="Insert version">version()</dialog><info title="Info window"></info></function>

18349

18350

18351

<description>Fairly portable uname interface. Returns a tuple of strings

18352

(system, node, release, version,

18353

machine, processor) identifying the underlying

18354

platform.

18355

Note that unlike the os.uname() function this also returns

18356

possible processor information as additional tuple entry.

18357

Entries which cannot be determined are set to ''.</description>

18358

18359

<insert>uname()</insert><dialog title="Insert uname">uname()</dialog><info title="Info window"></info></function>

18360

18361

</group>

18362

18363

18364

<description>Version interface for JPython.

18365

Returns a tuple (release, vendor, vminfo,

18366

osinfo) with vminfo being a tuple (vm_name,

18367

vm_release, vm_vendor) and osinfo being a tuple

18368

(os_name, os_version, os_arch).

18369

Values which cannot be determined are set to the defaults

18370

given as parameters (which all default to '').</description>

18371

<param name="release" optional="0" default="''">release</param><param name="vendor" optional="0" default="''">vendor</param><param name="vminfo" optional="0" default="(''">vminfo</param><param name="''" optional="0">''</param><param name="'')" optional="0">'')</param><param name="osinfo" optional="0" default="(''">osinfo</param><param name="''" optional="0">''</param><param name="'')'')" optional="0">'')'')</param>

18372

<insert>java_ver(release, vendor, vminfo, '', ''), osinfo, '', '')''))</insert><dialog title="Insert java_ver">java_ver(%0, %1, %2, %3, %4, %5, %6, %7)</dialog><info title="Info window"></info></function>

18373

18374

</group>

18375

18376

18377

<description>Get additional version information from the Windows Registry

18378

and return a tuple (version, csd, ptype)

18379

referring to version number, CSD level and OS type (multi/single

18380

processor).

18381

As a hint: ptype is 'Uniprocessor Free' on single

18382

processor NT machines and 'Multiprocessor Free' on multi

18383

processor machines. The 'Free' refers to the OS version being

18384

free of debugging code. It could also state 'Checked' which

18385

means the OS version uses debugging code, i.e. code that

18386

checks arguments, ranges, etc.

18387

[note]

18388

This function only works if Mark Hammond's win32all

18389

package is installed and (obviously) only runs on Win32

18390

compatible platforms.

18391

</description>

18392

<param name="release" optional="0" default="''">release</param><param name="version" optional="0" default="''">version</param><param name="csd" optional="0" default="''">csd</param><param name="ptype" optional="0" default="'' ptype=''">ptype</param>

18393

<insert>win32_ver(release, version, csd, ptype)</insert><dialog title="Insert win32_ver">win32_ver(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

18394

18395

18396

<description>Portable popen() interface. Find a working popen

18397

implementation preferring win32pipe.popen(). On Windows

18398

NT, win32pipe.popen() should work; on Windows 9x it hangs

18399

due to bugs in the MS C library.

18400

% This KnowledgeBase article appears to be missing...

18401

%See also MS KnowledgeBase article Q150956{}.</description>

18402

<param name="cmd" optional="0">cmd</param><param name="mode" optional="0" default="'r'">mode</param><param name="bufsize" optional="0" default="None bufsize=None">bufsize</param>

18403

<insert>popen(cmd, mode, bufsize)</insert><dialog title="Insert popen">popen(%0, %1, %2)</dialog><info title="Info window"></info></function>

18404

18405

</group>

18406

18407

18408

<description>Get Mac OS version information and return it as tuple

18409

(release, versioninfo, machine) with

18410

versioninfo being a tuple (version,

18411

dev_stage, non_release_version).

18412

Entries which cannot be determined are set to ''. All tuple

18413

entries are strings.

18414

Documentation for the underlying gestalt() API is

18415

available online at http://www.rgaros.nl/gestalt/.</description>

18416

<param name="release" optional="0" default="''">release</param><param name="versioninfo" optional="0" default="(''">versioninfo</param><param name="''" optional="0">''</param><param name="'')" optional="0">'')</param><param name="machine" optional="0" default="'' machine=''">machine</param>

18417

<insert>mac_ver(release, versioninfo, '', ''), machine)</insert><dialog title="Insert mac_ver">mac_ver(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

18418

18419

</group>

18420

18421

18422

<description>Tries to determine the name of the OS distribution name

18423

Returns a tuple (distname, version, id)

18424

which defaults to the args given as parameters.</description>

18425

<param name="distname" optional="0" default="''">distname</param><param name="version" optional="0" default="''">version</param><param name="id" optional="0" default="''">id</param><param name="supported_dists" optional="0" default="('SuSE'">supported_dists</param><param name="'debian'" optional="0">'debian'</param><param name="'redhat'" optional="0">'redhat'</param><param name="'mandrake')'mandrake')" optional="0">'mandrake')'mandrake')</param>

18426

<insert>dist(distname, version, id, supported_dists, 'debian', 'redhat', 'mandrake')'mandrake'))</insert><dialog title="Insert dist">dist(%0, %1, %2, %3, %4, %5, %6)</dialog><info title="Info window"></info></function>

18427

18428

18429

<description>Tries to determine the libc version against which the file

18430

executable (defaults to the Python interpreter) is linked. Returns

18431

a tuple of strings (lib, version) which default

18432

to the given parameters in case the lookup fails.

18433

Note that this function has intimate knowledge of how different

18434

libc versions add symbols to the executable is probably only

18435

useable for executables compiled using gcc.

18436

The file is read and scanned in chunks of chunksize bytes.</description>

18437

<param name="executable" optional="0" default="sys.executable">executable</param><param name="lib" optional="0" default="''">lib</param><param name="version" optional="0" default="''">version</param><param name="chunksize" optional="0" default="2048 chunksize=2048">chunksize</param>

18438

<insert>libc_ver(executable, lib, version, chunksize)</insert><dialog title="Insert libc_ver">libc_ver(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

18439

18440

</group>

18441

</group>

18442

</group>

18443

18444

18445

<description>Set handlers for asynchronous events.

18446

This module provides mechanisms to use signal handlers in Python.

18447

Some general rules for working with signals and their handlers:

18448

A handler for a particular signal, once set, remains installed until

18449

it is explicitly reset (Python emulates the BSD style interface

18450

regardless of the underlying implementation), with the exception of

18451

the handler for SIGCHLD, which follows the underlying

18452

implementation.

18453

There is no way to ``block'' signals temporarily from critical

18454

sections (since this is not supported by all flavors).

18455

Although Python signal handlers are called asynchronously as far as

18456

the Python user is concerned, they can only occur between the

18457

``atomic'' instructions of the Python interpreter. This means that

18458

signals arriving during long calculations implemented purely in C

18459

(such as regular expression matches on large bodies of text) may be

18460

delayed for an arbitrary amount of time.

18461

When a signal arrives during an I/O operation, it is possible that the

18462

I/O operation raises an exception after the signal handler returns.

18463

This is dependent on the underlying system's semantics regarding

18464

interrupted system calls.

18465

Because the signal handler always returns, it makes little sense to

18466

catch synchronous errors like SIGFPE or SIGSEGV.

18467

Python installs a small number of signal handlers by default:

18468

SIGPIPE is ignored (so write errors on pipes and sockets can be

18469

reported as ordinary Python exceptions) and SIGINT is translated

18470

into a KeyboardInterrupt exception. All of these can be

18471

overridden.

18472

Some care must be taken if both signals and threads are used in the

18473

same program. The fundamental thing to remember in using signals and

18474

threads simultaneously is: perform signal() operations

18475

in the main thread of execution. Any thread can perform an

18476

alarm(), getsignal(), or pause();

18477

only the main thread can set a new signal handler, and the main thread

18478

will be the only one to receive signals (this is enforced by the

18479

Python signal module, even if the underlying thread

18480

implementation supports sending signals to individual threads). This

18481

means that signals can't be used as a means of inter-thread

18482

communication. Use locks instead.

18483

The variables defined in the signal module are:

18484

{SIG_DFL}

18485

This is one of two standard signal handling options; it will simply

18486

perform the default function for the signal. For example, on most

18487

systems the default action for SIGQUIT is to dump core

18488

and exit, while the default action for SIGCLD is to

18489

simply ignore it.

18490

{SIG_IGN}

18491

This is another standard signal handler, which will simply ignore

18492

the given signal.

18493

{SIG*}

18494

All the signal numbers are defined symbolically. For example, the

18495

hangup signal is defined as signal.SIGHUP; the variable names

18496

are identical to the names used in C programs, as found in

18497

<signal.h>.

18498

The man page for `signal()' lists the existing

18499

signals (on some systems this is signal{2}, on others the

18500

list is in signal{7}).

18501

Note that not all systems define the same set of signal names; only

18502

those names defined by the system are defined by this module.

18503

{NSIG}

18504

One more than the number of the highest signal number.

18505

The signal module defines the following functions:

18506

</description>

18507

18508

<description>If time is non-zero, this function requests that a

18509

SIGALRM signal be sent to the process in time seconds.

18510

Any previously scheduled alarm is canceled (only one alarm can

18511

be scheduled at any time). The returned value is then the number of

18512

seconds before any previously set alarm was to have been delivered.

18513

If time is zero, no alarm id scheduled, and any scheduled

18514

alarm is canceled. The return value is the number of seconds

18515

remaining before a previously scheduled alarm. If the return value

18516

is zero, no alarm is currently scheduled. (See the man page

18517

alarm{2}.)

18518

Availability: .</description>

18519

<param name="timetime" optional="0">timetime</param>

18520

<insert>alarm(timetime)</insert><dialog title="Insert alarm">alarm(%0)</dialog><info title="Info window"></info></function>

18521

18522

18523

<description>Return the current signal handler for the signal signalnum.

18524

The returned value may be a callable Python object, or one of the

18525

special values signal.SIG_IGN, signal.SIG_DFL or

18526

None. Here, signal.SIG_IGN means that the

18527

signal was previously ignored, signal.SIG_DFL means that the

18528

default way of handling the signal was previously in use, and

18529

None means that the previous signal handler was not installed

18530

from Python.</description>

18531

<param name="signalnumsignalnum" optional="0">signalnumsignalnum</param>

18532

<insert>getsignal(signalnumsignalnum)</insert><dialog title="Insert getsignal">getsignal(%0)</dialog><info title="Info window"></info></function>

18533

18534

18535

<description>Cause the process to sleep until a signal is received; the

18536

appropriate handler will then be called. Returns nothing. Not on

18537

Windows. (See the man page signal{2}.)</description>

18538

18539

<insert>pause()</insert><dialog title="Insert pause">pause()</dialog><info title="Info window"></info></function>

18540

18541

18542

<description>Set the handler for signal signalnum to the function

18543

handler. handler can be a callable Python object

18544

taking two arguments (see below), or

18545

one of the special values signal.SIG_IGN or

18546

signal.SIG_DFL. The previous signal handler will be returned

18547

(see the description of getsignal() above). (See the

18548

man page signal{2}.)

18549

When threads are enabled, this function can only be called from the

18550

main thread; attempting to call it from other threads will cause a

18551

ValueError exception to be raised.

18552

The handler is called with two arguments: the signal number

18553

and the current stack frame (None or a frame object; see the

18554

reference manual for a description of frame objects).

18555

frame</description>

18556

<param name="signalnum" optional="0">signalnum</param><param name="handler handler" optional="0">handler handler</param>

18557

<insert>signal(signalnum, handler handler)</insert><dialog title="Insert signal">signal(%0, %1)</dialog><info title="Info window"></info></function>

18558

18559

18560

</group>

18561

</group>

18562

18563

<description>Low-level networking interface.

18564

This module provides access to the BSD socket interface.

18565

It is available on all modern systems, Windows, MacOS, BeOS,

18566

OS/2, and probably additional platforms.

18567

For an introduction to socket programming (in C), see the following

18568

papers: An Introductory 4.3BSD Interprocess Communication

18569

Tutorial, by Stuart Sechrest and An Advanced 4.3BSD

18570

Interprocess Communication Tutorial, by Samuel J. Leffler et al,

18571

both in the Programmer's Manual, Supplementary Documents 1

18572

(sections PS1:7 and PS1:8). The platform-specific reference material

18573

for the various socket-related system calls are also a valuable source

18574

of information on the details of socket semantics. For , refer

18575

to the manual pages; for Windows, see the WinSock (or Winsock 2)

18576

specification.

18577

For IPv6-ready APIs, readers may want to refer to 2553 titled

18578

Basic Socket Interface Extensions for IPv6.

18579

The Python interface is a straightforward transliteration of the

18580

system call and library interface for sockets to Python's

18581

object-oriented style: the socket() function returns a

18582

socket objectsocket whose methods implement the

18583

various socket system calls. Parameter types are somewhat

18584

higher-level than in the C interface: as with read() and

18585

write() operations on Python files, buffer allocation on

18586

receive operations is automatic, and buffer length is implicit on send

18587

operations.

18588

Socket addresses are represented as follows:

18589

A single string is used for the AF_UNIX address family.

18590

A pair (host, port) is used for the

18591

AF_INET address family, where host is a string

18592

representing either a hostname in Internet domain notation like

18593

'daring.cwi.nl' or an IPv4 address like '100.50.200.5',

18594

and port is an integral port number.

18595

For AF_INET6 address family, a four-tuple

18596

(host, port, flowinfo, scopeid) is

18597

used, where flowinfo and scopeid represents

18598

sin6_flowinfo and sin6_scope_id member in

18599

struct sockaddr_in6 in C.

18600

For socket module methods, flowinfo and scopeid

18601

can be omitted just for backward compatibility. Note, however,

18602

omission of scopeid can cause problems in manipulating scoped

18603

IPv6 addresses. Other address families are currently not supported.

18604

The address format required by a particular socket object is

18605

automatically selected based on the address family specified when the

18606

socket object was created.

18607

For IPv4 addresses, two special forms are accepted instead of a host

18608

address: the empty string represents INADDR_ANY, and the string

18609

'<broadcast>' represents INADDR_BROADCAST.

18610

The behavior is not available for IPv6 for backward compatibility,

18611

therefore, you may want to avoid these if you intend to support IPv6 with

18612

your Python programs.

18613

If you use a hostname in the host portion of IPv4/v6 socket

18614

address, the program may show a nondeterministic behavior, as Python

18615

uses the first address returned from the DNS resolution. The socket

18616

address will be resolved differently into an actual IPv4/v6 address,

18617

depending on the results from DNS resolution and/or the host

18618

configuration. For deterministic behavior use a numeric address in

18619

host portion.

18620

All errors raise exceptions. The normal exceptions for invalid

18621

argument types and out-of-memory conditions can be raised; errors

18622

related to socket or address semantics raise the error

18623

socket.error.

18624

Non-blocking mode is supported through

18625

setblocking(). A generalization of this based on timeouts

18626

is supported through settimeout().

18627

The module socket exports the following constants and functions:

18628

{error}

18629

This exception is raised for socket-related errors.

18630

The accompanying value is either a string telling what went wrong or a

18631

pair (errno, string)

18632

representing an error returned by a system

18633

call, similar to the value accompanying os.error.

18634

See the module errnoerrno, which contains

18635

names for the error codes defined by the underlying operating system.

18636

{herror}

18637

This exception is raised for address-related errors, i.e. for

18638

functions that use h_errno in the C API, including

18639

gethostbyname_ex() and gethostbyaddr().

18640

The accompanying value is a pair (h_errno, string)

18641

representing an error returned by a library call. string

18642

represents the description of h_errno, as returned by

18643

the hstrerror() C function.

18644

{gaierror}

18645

This exception is raised for address-related errors, for

18646

getaddrinfo() and getnameinfo().

18647

The accompanying value is a pair (error, string)

18648

representing an error returned by a library call.

18649

string represents the description of error, as returned

18650

by the gai_strerror() C function.

18651

{timeout}

18652

This exception is raised when a timeout occurs on a socket which has

18653

had timeouts enabled via a prior call to settimeout(). The

18654

accompanying value is a string whose value is currently always ``timed

18655

out''.

18656

New in version 2.3

18657

{AF_UNIX}

18658

AF_INET

18659

AF_INET6

18660

These constants represent the address (and protocol) families,

18661

used for the first argument to socket(). If the

18662

AF_UNIX constant is not defined then this protocol is

18663

unsupported.

18664

{SOCK_STREAM}

18665

SOCK_DGRAM

18666

SOCK_RAW

18667

SOCK_RDM

18668

SOCK_SEQPACKET

18669

These constants represent the socket types,

18670

used for the second argument to socket().

18671

(Only SOCK_STREAM and

18672

SOCK_DGRAM appear to be generally useful.)

18673

{SO_*}

18674

SOMAXCONN

18675

MSG_*

18676

SOL_*

18677

IPPROTO_*

18678

IPPORT_*

18679

INADDR_*

18680

IP_*

18681

IPV6_*

18682

EAI_*

18683

AI_*

18684

NI_*

18685

TCP_*

18686

Many constants of these forms, documented in the documentation on

18687

sockets and/or the IP protocol, are also defined in the socket module.

18688

They are generally used in arguments to the setsockopt() and

18689

getsockopt() methods of socket objects. In most cases, only

18690

those symbols that are defined in the header files are defined;

18691

for a few symbols, default values are provided.

18692

{has_ipv6}

18693

This constant contains a boolean value which indicates if IPv6 is

18694

supported on this platform.

18695

New in version 2.3

18696

</description>

18697

18698

<description>Resolves the host/port argument, into a sequence of

18699

5-tuples that contain all the necessary argument for the sockets

18700

manipulation. host is a domain name, a string representation of

18701

IPv4/v6 address or None.

18702

port is a string service name (like 'http'), a numeric

18703

port number or None.

18704

The rest of the arguments are optional and must be numeric if

18705

specified. For host and port, by passing either an empty

18706

string or None, you can pass NULL to the C API. The

18707

getaddrinfo() function returns a list of 5-tuples with

18708

the following structure:

18709

(family, socktype, proto, canonname,

18710

sockaddr)

18711

family, socktype, proto are all integer and are meant to

18712

be passed to the socket() function.

18713

canonname is a string representing the canonical name of the host.

18714

It can be a numeric IPv4/v6 address when AI_CANONNAME is specified

18715

for a numeric host.

18716

sockaddr is a tuple describing a socket address, as described above.

18717

See the source for the httplib and other library modules

18718

for a typical usage of the function.

18719

New in version 2.2</description>

18720

<param name="host" optional="0">host</param><param name="port" optional="0">port</param><param name="family" optional="1">family</param><param name="socktype" optional="1">socktype</param><param name="proto" optional="1">proto</param><param name="flags" optional="1">flags</param>

18721

<insert>getaddrinfo(host, port, [family], [socktype], [proto], [flags])</insert><dialog title="Insert getaddrinfo">getaddrinfo(%0, %1, %2, %3, %4, %5)</dialog><info title="Info window"></info></function>

18722

18723

18724

<description>Return a fully qualified domain name for name.

18725

If name is omitted or empty, it is interpreted as the local

18726

host. To find the fully qualified name, the hostname returned by

18727

gethostbyaddr() is checked, then aliases for the host, if

18728

available. The first name which includes a period is selected. In

18729

case no fully qualified domain name is available, the hostname is

18730

returned.

18731

New in version 2.0</description>

18732

18733

<insert>getfqdn(name)</insert><dialog title="Insert getfqdn">getfqdn(%0)</dialog><info title="Info window"></info></function>

18734

18735

18736

<description>Translate a host name to IPv4 address format. The IPv4 address is

18737

returned as a string, such as '100.50.200.5'. If the host name

18738

is an IPv4 address itself it is returned unchanged. See

18739

gethostbyname_ex() for a more complete interface.

18740

gethostbyname() does not support IPv6 name resolution, and

18741

getaddrinfo() should be used instead for IPv4/v6 dual stack support.</description>

18742

<param name="hostnamehostname" optional="0">hostnamehostname</param>

18743

<insert>gethostbyname(hostnamehostname)</insert><dialog title="Insert gethostbyname">gethostbyname(%0)</dialog><info title="Info window"></info></function>

18744

18745

18746

<description>Translate a host name to IPv4 address format, extended interface.

18747

Return a triple (hostname, aliaslist,

18748

ipaddrlist) where

18749

hostname is the primary host name responding to the given

18750

ip_address, aliaslist is a (possibly empty) list of

18751

alternative host names for the same address, and ipaddrlist is

18752

a list of IPv4 addresses for the same interface on the same

18753

host (often but not always a single address).

18754

gethostbyname_ex() does not support IPv6 name resolution, and

18755

getaddrinfo() should be used instead for IPv4/v6 dual stack support.</description>

18756

<param name="hostnamehostname" optional="0">hostnamehostname</param>

18757

<insert>gethostbyname_ex(hostnamehostname)</insert><dialog title="Insert gethostbyname_ex">gethostbyname_ex(%0)</dialog><info title="Info window"></info></function>

18758

18759

18760

<description>Return a string containing the hostname of the machine where the Python interpreter is currently executing.

18761

If you want to know the current machine's IP address, you may want to use

18762

gethostbyname(gethostname()).

18763

This operation assumes that there is a valid address-to-host mapping for

18764

the host, and the assumption does not always hold.

18765

Note: gethostname() doesn't always return the fully qualified

18766

domain name; use gethostbyaddr(gethostname())

18767

(see below).</description>

18768

18769

<insert>gethostname()</insert><dialog title="Insert gethostname">gethostname()</dialog><info title="Info window"></info></function>

18770

18771

18772

<description>Return a triple (hostname, aliaslist,

18773

ipaddrlist) where hostname is the primary host name

18774

responding to the given ip_address, aliaslist is a

18775

(possibly empty) list of alternative host names for the same address,

18776

and ipaddrlist is a list of IPv4/v6 addresses for the same interface

18777

on the same host (most likely containing only a single address).

18778

To find the fully qualified domain name, use the function

18779

getfqdn().

18780

gethostbyaddr supports both IPv4 and IPv6.</description>

18781

<param name="ip_addressip_address" optional="0">ip_addressip_address</param>

18782

<insert>gethostbyaddr(ip_addressip_address)</insert><dialog title="Insert gethostbyaddr">gethostbyaddr(%0)</dialog><info title="Info window"></info></function>

18783

18784

18785

<description>Translate a socket address sockaddr into a 2-tuple

18786

(host, port).

18787

Depending on the settings of flags, the result can contain a

18788

fully-qualified domain name or numeric address representation in

18789

host. Similarly, port can contain a string port name or a

18790

numeric port number.

18791

New in version 2.2</description>

18792

<param name="sockaddr" optional="0">sockaddr</param><param name="flags flags" optional="0">flags flags</param>

18793

<insert>getnameinfo(sockaddr, flags flags)</insert><dialog title="Insert getnameinfo">getnameinfo(%0, %1)</dialog><info title="Info window"></info></function>

18794

18795

18796

<description>Translate an Internet protocol name (for example, 'icmp') to a constant

18797

suitable for passing as the (optional) third argument to the

18798

socket() function. This is usually only needed for sockets

18799

opened in ``raw'' mode (SOCK_RAW); for the normal socket

18800

modes, the correct protocol is chosen automatically if the protocol is

18801

omitted or zero.</description>

18802

<param name="protocolnameprotocolname" optional="0">protocolnameprotocolname</param>

18803

<insert>getprotobyname(protocolnameprotocolname)</insert><dialog title="Insert getprotobyname">getprotobyname(%0)</dialog><info title="Info window"></info></function>

18804

18805

18806

<description>Translate an Internet service name and protocol name to a port number

18807

for that service. The protocol name should be 'tcp' or

18808

'udp'.</description>

18809

<param name="servicename" optional="0">servicename</param><param name="protocolname protocolname" optional="0">protocolname protocolname</param>

18810

<insert>getservbyname(servicename, protocolname protocolname)</insert><dialog title="Insert getservbyname">getservbyname(%0, %1)</dialog><info title="Info window"></info></function>

18811

18812

18813

<description>Create a new socket using the given address family, socket type and

18814

protocol number. The address family should be AF_INET, AF_INET6 or

18815

AF_UNIX. The socket type should be SOCK_STREAM,

18816

SOCK_DGRAM or perhaps one of the other SOCK_ constants.

18817

The protocol number is usually zero and may be omitted in that case.</description>

18818

<param name="family" optional="0">family</param><param name="type" optional="0">type</param><param name="proto" optional="1">proto</param>

18819

<insert>socket(family, type, [proto])</insert><dialog title="Insert socket">socket(%0, %1, %2)</dialog><info title="Info window"></info></function>

18820

18821

18822

<description>Initiate a SSL connection over the socket sock. keyfile is

18823

the name of a PEM formatted file that contains your private

18824

key. certfile is a PEM formatted certificate chain file. On

18825

success, a new SSLObject is returned.

18826

This does not do any certificate verification!</description>

18827

<param name="sock" optional="0">sock</param><param name="keyfile" optional="1">keyfile</param><param name="certfile" optional="1">certfile</param>

18828

<insert>ssl(sock, [keyfile], [certfile])</insert><dialog title="Insert ssl">ssl(%0, %1, %2)</dialog><info title="Info window"></info></function>

18829

18830

18831

<description>Build a socket object from an existing file descriptor (an integer as

18832

returned by a file object's fileno() method). Address family,

18833

socket type and protocol number are as for the socket() function

18834

above. The file descriptor should refer to a socket, but this is not

18835

checked --- subsequent operations on the object may fail if the file

18836

descriptor is invalid. This function is rarely needed, but can be

18837

used to get or set socket options on a socket passed to a program as

18838

standard input or output (such as a server started by the inet

18839

daemon). The socket is assumed to be in blocking mode.

18840

Availability: .</description>

18841

<param name="fd" optional="0">fd</param><param name="family" optional="0">family</param><param name="type" optional="0">type</param><param name="proto" optional="1">proto</param>

18842

<insert>fromfd(fd, family, type, [proto])</insert><dialog title="Insert fromfd">fromfd(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

18843

18844

18845

<description>Convert 32-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 4-byte swap operation.</description>

18848

18849

<insert>ntohl(xx)</insert><dialog title="Insert ntohl">ntohl(%0)</dialog><info title="Info window"></info></function>

18850

18851

18852

<description>Convert 16-bit integers from network to host 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 2-byte swap operation.</description>

18855

18856

<insert>ntohs(xx)</insert><dialog title="Insert ntohs">ntohs(%0)</dialog><info title="Info window"></info></function>

18857

18858

18859

<description>Convert 32-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 4-byte swap operation.</description>

18862

18863

<insert>htonl(xx)</insert><dialog title="Insert htonl">htonl(%0)</dialog><info title="Info window"></info></function>

18864

18865

18866

<description>Convert 16-bit integers from host to network byte order. On machines

18867

where the host byte order is the same as network byte order, this is a

18868

no-op; otherwise, it performs a 2-byte swap operation.</description>

18869

18870

<insert>htons(xx)</insert><dialog title="Insert htons">htons(%0)</dialog><info title="Info window"></info></function>

18871

18872

18873

<description>Convert an IPv4 address from dotted-quad string format (for example,

18874

'123.45.67.89') to 32-bit packed binary format, as a string four

18875

characters in length. This is useful when conversing with a program

18876

that uses the standard C library and needs objects of type

18877

struct in_addr, which is the C type for the 32-bit packed

18878

binary this function returns.

18879

If the IPv4 address string passed to this function is invalid,

18880

socket.error will be raised. Note that exactly what is

18881

valid depends on the underlying C implementation of

18882

inet_aton().

18883

inet_aton() does not support IPv6, and

18884

getnameinfo() should be used instead for IPv4/v6 dual stack

18885

support.</description>

18886

<param name="ip_stringip_string" optional="0">ip_stringip_string</param>

18887

<insert>inet_aton(ip_stringip_string)</insert><dialog title="Insert inet_aton">inet_aton(%0)</dialog><info title="Info window"></info></function>

18888

18889

18890

<description>Convert a 32-bit packed IPv4 address (a string four characters in

18891

length) to its standard dotted-quad string representation (for

18892

example, '123.45.67.89'). This is useful when conversing with a

18893

program that uses the standard C library and needs objects of type

18894

struct in_addr, which is the C type for the 32-bit packed

18895

binary data this function takes as an argument.

18896

If the string passed to this function is not exactly 4 bytes in

18897

length, socket.error will be raised.

18898

inet_ntoa() does not support IPv6, and

18899

getnameinfo() should be used instead for IPv4/v6 dual stack

18900

support.</description>

18901

<param name="packed_ippacked_ip" optional="0">packed_ippacked_ip</param>

18902

<insert>inet_ntoa(packed_ippacked_ip)</insert><dialog title="Insert inet_ntoa">inet_ntoa(%0)</dialog><info title="Info window"></info></function>

18903

18904

18905

<description>Convert an IP address from its family-specific string format to a packed,

18906

binary format.

18907

inet_pton() is useful when a library or network protocol calls for

18908

an object of type struct in_addr (similar to inet_aton())

18909

or struct in6_addr.

18910

Supported values for address_family are currently

18911

AF_INET and AF_INET6.

18912

If the IP address string ip_string is invalid,

18913

socket.error will be raised. Note that exactly what is valid

18914

depends on both the value of address_family and the underlying

18915

implementation of inet_pton().

18916

Availability: (maybe not all platforms).

18917

New in version 2.3</description>

18918

<param name="address_family" optional="0">address_family</param><param name="ip_string ip_string" optional="0">ip_string ip_string</param>

18919

<insert>inet_pton(address_family, ip_string ip_string)</insert><dialog title="Insert inet_pton">inet_pton(%0, %1)</dialog><info title="Info window"></info></function>

18920

18921

18922

<description>Convert a packed IP address (a string of some number of characters) to

18923

its standard, family-specific string representation (for example,

18924

'7.10.0.5' or '5aef:2b::8')

18925

inet_ntop() is useful when a library or network protocol returns

18926

an object of type struct in_addr (similar to inet_ntoa())

18927

or struct in6_addr.

18928

Supported values for address_family are currently

18929

AF_INET and AF_INET6.

18930

If the string packed_ip is not the correct length for the

18931

specified address family, ValueError will be raised. A

18932

socket.error is raised for errors from the call to

18933

inet_ntop().

18934

Availability: (maybe not all platforms).

18935

New in version 2.3</description>

18936

<param name="address_family" optional="0">address_family</param><param name="packed_ip packed_ip" optional="0">packed_ip packed_ip</param>

18937

<insert>inet_ntop(address_family, packed_ip packed_ip)</insert><dialog title="Insert inet_ntop">inet_ntop(%0, %1)</dialog><info title="Info window"></info></function>

18938

18939

18940

<description>Return the default timeout in floating seconds for new socket objects.

18941

A value of None indicates that new socket objects have no timeout.

18942

When the socket module is first imported, the default is None.

18943

New in version 2.3</description>

18944

18945

<insert>getdefaulttimeout()</insert><dialog title="Insert getdefaulttimeout">getdefaulttimeout()</dialog><info title="Info window"></info></function>

18946

18947

18948

<description>Set the default timeout in floating seconds for new socket objects.

18949

A value of None indicates that new socket objects have no timeout.

18950

When the socket module is first imported, the default is None.

18951

New in version 2.3</description>

18952

<param name="timeouttimeout" optional="0">timeouttimeout</param>

18953

<insert>setdefaulttimeout(timeouttimeout)</insert><dialog title="Insert setdefaulttimeout">setdefaulttimeout(%0)</dialog><info title="Info window"></info></function>

18954

18955

18956

<description>Socket objects have the following methods. Except for

18957

makefile() these correspond to system calls

18958

applicable to sockets.

18959

</description>

18960

18961

<description>Accept a connection.

18962

The socket must be bound to an address and listening for connections.

18963

The return value is a pair (conn, address)

18964

where conn is a new socket object usable to send and

18965

receive data on the connection, and address is the address bound

18966

to the socket on the other end of the connection.</description>

18967

18968

<insert>accept()</insert><dialog title="Insert accept">accept()</dialog><info title="Info window"></info></function>

18969

18970

18971

<description>Bind the socket to address. The socket must not already be bound.

18972

(The format of address depends on the address family --- see

18973

above.) This method has historically accepted a pair

18974

of parameters for AF_INET addresses instead of only a

18975

tuple. This was never intentional and is no longer be available in

18976

Python 2.0.</description>

18977

<param name="addressaddress" optional="0">addressaddress</param>

18978

<insert>bind(addressaddress)</insert><dialog title="Insert bind">bind(%0)</dialog><info title="Info window"></info></function>

18979

18980

18981

<description>Close the socket. All future operations on the socket object will fail.

18982

The remote end will receive no more data (after queued data is flushed).

18983

Sockets are automatically closed when they are garbage-collected.</description>

18984

18985

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

18986

18987

18988

<description>Connect to a remote socket at address.

18989

(The format of address depends on the address family --- see

18990

above.) This method has historically accepted a pair

18991

of parameters for AF_INET addresses instead of only a

18992

tuple. This was never intentional and is no longer available in

18993

Python 2.0 and later.</description>

18994

<param name="addressaddress" optional="0">addressaddress</param>

18995

<insert>connect(addressaddress)</insert><dialog title="Insert connect">connect(%0)</dialog><info title="Info window"></info></function>

18996

18997

18998

<description>Like connect(address), but return an error indicator

18999

instead of raising an exception for errors returned by the C-level

19000

connect() call (other problems, such as ``host not found,''

19001

can still raise exceptions). The error indicator is 0 if the

19002

operation succeeded, otherwise the value of the errno

19003

variable. This is useful to support, for example, asynchronous connects.

19004

This method has historically accepted a pair of

19005

parameters for AF_INET addresses instead of only a tuple.

19006

This was never intentional and is no longer be available in Python

19007

2.0 and later.</description>

19008

<param name="addressaddress" optional="0">addressaddress</param>

19009

<insert>connect_ex(addressaddress)</insert><dialog title="Insert connect_ex">connect_ex(%0)</dialog><info title="Info window"></info></function>

19010

19011

19012

<description>Return the socket's file descriptor (a small integer). This is useful

19013

with select.select().

19014

Under Windows the small integer returned by this method cannot be used where

19015

a file descriptor can be used (such as os.fdopen()). does

19016

not have this limitation.</description>

19017

19018

<insert>fileno()</insert><dialog title="Insert fileno">fileno()</dialog><info title="Info window"></info></function>

19019

19020

19021

<description>Return the remote address to which the socket is connected. This is

19022

useful to find out the port number of a remote IPv4/v6 socket, for instance.

19023

(The format of the address returned depends on the address family ---

19024

see above.) On some systems this function is not supported.</description>

19025

19026

<insert>getpeername()</insert><dialog title="Insert getpeername">getpeername()</dialog><info title="Info window"></info></function>

19027

19028

19029

<description>Return the socket's own address. This is useful to find out the port

19030

number of an IPv4/v6 socket, for instance.

19031

(The format of the address returned depends on the address family ---

19032

see above.)</description>

19033

19034

<insert>getsockname()</insert><dialog title="Insert getsockname">getsockname()</dialog><info title="Info window"></info></function>

19035

19036

19037

<description>Return the value of the given socket option (see the man page

19038

getsockopt{2}). The needed symbolic constants

19039

(SO_* etc.) are defined in this module. If buflen

19040

is absent, an integer option is assumed and its integer value

19041

is returned by the function. If buflen is present, it specifies

19042

the maximum length of the buffer used to receive the option in, and

19043

this buffer is returned as a string. It is up to the caller to decode

19044

the contents of the buffer (see the optional built-in module

19045

struct for a way to decode C structures encoded as strings).</description>

19046

<param name="level" optional="0">level</param><param name="optname" optional="0">optname</param><param name="buflen" optional="1">buflen</param>

19047

<insert>getsockopt(level, optname, [buflen])</insert><dialog title="Insert getsockopt">getsockopt(%0, %1, %2)</dialog><info title="Info window"></info></function>

19048

19049

19050

<description>Listen for connections made to the socket. The backlog argument

19051

specifies the maximum number of queued connections and should be at

19052

least 1; the maximum value is system-dependent (usually 5).</description>

19053

<param name="backlogbacklog" optional="0">backlogbacklog</param>

19054

<insert>listen(backlogbacklog)</insert><dialog title="Insert listen">listen(%0)</dialog><info title="Info window"></info></function>

19055

19056

19057

<description>Return a file object associated with the socket. (File objects

19058

are described in bltin-file-objects, ``File Objects.'')

19059

The file object references a dup()ped version of the

19060

socket file descriptor, so the file object and socket object may be

19061

closed or garbage-collected independently.

19062

The socket should be in blocking mode.

19063

</description>

19064

<param name="mode" optional="0">mode</param><param name="bufsize" optional="1">bufsize</param>

19065

<insert>makefile(mode, [bufsize])</insert><dialog title="Insert makefile">makefile(%0, %1)</dialog><info title="Info window"></info></function>

19066

19067

19068

<description>Receive data from the socket. The return value is a string representing

19069

the data received. The maximum amount of data to be received

19070

at once is specified by bufsize. See the manual page

19071

recv{2} for the meaning of the optional argument

19072

flags; it defaults to zero.</description>

19073

<param name="bufsize" optional="0">bufsize</param><param name="flags" optional="1">flags</param>

19074

<insert>recv(bufsize, [flags])</insert><dialog title="Insert recv">recv(%0, %1)</dialog><info title="Info window"></info></function>

19075

19076

19077

<description>Receive data from the socket. The return value is a pair

19078

(string, address) where string is a string

19079

representing the data received and address is the address of the

19080

socket sending the data. The optional flags argument has the

19081

same meaning as for recv() above.

19082

(The format of address depends on the address family --- see above.)</description>

19083

<param name="bufsize" optional="0">bufsize</param><param name="flags" optional="1">flags</param>

19084

<insert>recvfrom(bufsize, [flags])</insert><dialog title="Insert recvfrom">recvfrom(%0, %1)</dialog><info title="Info window"></info></function>

19085

19086

19087

<description>Send data to the socket. The socket must be connected to a remote

19088

socket. The optional flags argument has the same meaning as for

19089

recv() above. Returns the number of bytes sent.

19090

Applications are responsible for checking that all data has been sent;

19091

if only some of the data was transmitted, the application needs to

19092

attempt delivery of the remaining data.</description>

19093

<param name="string" optional="0">string</param><param name="flags" optional="1">flags</param>

19094

<insert>send(string, [flags])</insert><dialog title="Insert send">send(%0, %1)</dialog><info title="Info window"></info></function>

19095

19096

19097

<description>Send data to the socket. The socket must be connected to a remote

19098

socket. The optional flags argument has the same meaning as for

19099

recv() above. Unlike send(), this method continues

19100

to send data from string until either all data has been sent or

19101

an error occurs. None is returned on success. On error, an

19102

exception is raised, and there is no way to determine how much data,

19103

if any, was successfully sent.</description>

19104

<param name="string" optional="0">string</param><param name="flags" optional="1">flags</param>

19105

<insert>sendall(string, [flags])</insert><dialog title="Insert sendall">sendall(%0, %1)</dialog><info title="Info window"></info></function>

19106

19107

19108

<description>Send data to the socket. The socket should not be connected to a

19109

remote socket, since the destination socket is specified by

19110

address. The optional flags argument has the same

19111

meaning as for recv() above. Return the number of bytes sent.

19112

(The format of address depends on the address family --- see above.)</description>

19113

<param name="string" optional="0">string</param><param name="flags" optional="1">flags</param><param name="address address" optional="1">address address</param>

19114

<insert>sendto(string, [flags], [address address])</insert><dialog title="Insert sendto">sendto(%0, %1, %2)</dialog><info title="Info window"></info></function>

19115

19116

19117

<description>Set blocking or non-blocking mode of the socket: if flag is 0,

19118

the socket is set to non-blocking, else to blocking mode. Initially

19119

all sockets are in blocking mode. In non-blocking mode, if a

19120

recv() call doesn't find any data, or if a

19121

send() call can't immediately dispose of the data, a

19122

error exception is raised; in blocking mode, the calls

19123

block until they can proceed.

19124

s.setblocking(0) is equivalent to s.settimeout(0);

19125

s.setblocking(1) is equivalent to s.settimeout(None).</description>

19126

<param name="flagflag" optional="0">flagflag</param>

19127

<insert>setblocking(flagflag)</insert><dialog title="Insert setblocking">setblocking(%0)</dialog><info title="Info window"></info></function>

19128

19129

19130

<description>Set a timeout on blocking socket operations. The value argument

19131

can be a nonnegative float expressing seconds, or None.

19132

If a float is

19133

given, subsequent socket operations will raise an timeout

19134

exception if the timeout period value has elapsed before the

19135

operation has completed. Setting a timeout of None disables

19136

timeouts on socket operations.

19137

s.settimeout(0.0) is equivalent to s.setblocking(0);

19138

s.settimeout(None) is equivalent to s.setblocking(1).

19139

New in version 2.3</description>

19140

<param name="valuevalue" optional="0">valuevalue</param>

19141

<insert>settimeout(valuevalue)</insert><dialog title="Insert settimeout">settimeout(%0)</dialog><info title="Info window"></info></function>

19142

19143

19144

<description>Returns the timeout in floating seconds associated with socket

19145

operations, or None if no timeout is set. This reflects

19146

the last call to setblocking() or settimeout().

19147

New in version 2.3</description>

19148

19149

<insert>gettimeout()</insert><dialog title="Insert gettimeout">gettimeout()</dialog><info title="Info window"></info></function>

19150

19151

19152

<description>Set the value of the given socket option (see the manual page

19153

setsockopt{2}). The needed symbolic constants are defined in

19154

the socket module (SO_* etc.). The value can be an

19155

integer or a string representing a buffer. In the latter case it is

19156

up to the caller to ensure that the string contains the proper bits

19157

(see the optional built-in module

19158

structstruct for a way to encode C

19159

structures as strings).</description>

19160

<param name="level" optional="0">level</param><param name="optname" optional="0">optname</param><param name="value value" optional="0">value value</param>

19161

<insert>setsockopt(level, optname, value value)</insert><dialog title="Insert setsockopt">setsockopt(%0, %1, %2)</dialog><info title="Info window"></info></function>

19162

19163

19164

<description>Shut down one or both halves of the connection. If how is

19165

SHUT_RD, further receives are disallowed. If how is SHUT_WR,

19166

further sends are disallowed. If how is SHUT_RDWR, further sends

19167

and receives are disallowed.</description>

19168

<param name="howhow" optional="0">howhow</param>

19169

<insert>shutdown(howhow)</insert><dialog title="Insert shutdown">shutdown(%0)</dialog><info title="Info window"></info></function>

19170

19171

</group>

19172

19173

<description>SSL objects have the following methods.

19174

</description>

19175

19176

<description>Writes the string s to the on the object's SSL connection.

19177

The return value is the number of bytes written.</description>

19178

19179

<insert>write(ss)</insert><dialog title="Insert write">write(%0)</dialog><info title="Info window"></info></function>

19180

19181

19182

<description>If n is provided, read n bytes from the SSL connection, otherwise

19183

read until EOF. The return value is a string of the bytes read.</description>

19184

19185

19186

19187

</group>

19188

19189

</group>

19190

</group>

19191

19192

<description>Wait for I/O completion on multiple streams.

19193

This module provides access to the select()

19194

and poll() functions

19195

available in most operating systems. Note that on Windows, it only

19196

works for sockets; on other operating systems, it also works for other

19197

file types (in particular, on , it works on pipes). It cannot

19198

be used on regular files to determine whether a file has grown since

19199

it was last read.

19200

The module defines the following:

19201

{error}

19202

The exception raised when an error occurs. The accompanying value is

19203

a pair containing the numeric error code from errno and the

19204

corresponding string, as would be printed by the function

19205

perror().

19206

</description>

19207

19208

<description>(Not supported by all operating systems.) Returns a polling object,

19209

which supports registering and unregistering file descriptors, and

19210

then polling them for I/O events;

19211

see section~poll-objects below for the methods supported by

19212

polling objects.</description>

19213

19214

19215

19216

19217

<description>This is a straightforward interface to the select()

19218

system call. The first three arguments are sequences of `waitable

19219

objects': either integers representing file descriptors or

19220

objects with a parameterless method named fileno() returning

19221

such an integer. The three sequences of waitable objects are for input,

19222

output and `exceptional conditions', respectively. Empty sequences are

19223

allowed, but acceptance of three empty sequences is platform-dependent.

19224

(It is known to work on but not on Windows.) The optional

19225

timeout argument specifies a time-out as a floating point number

19226

in seconds. When the timeout argument is omitted the function

19227

blocks until at least one file descriptor is ready. A time-out value

19228

of zero specifies a poll and never blocks.

19229

The return value is a triple of lists of objects that are ready:

19230

subsets of the first three arguments. When the time-out is reached

19231

without a file descriptor becoming ready, three empty lists are

19232

returned.

19233

Among the acceptable object types in the sequences are Python file

19234

objects (e.g. sys.stdin, or objects returned by

19235

open() or os.popen()), socket objects

19236

returned by socket.socket().%

19237

(in module socket){socket()}

19238

(in module os){popen()}

19239

You may also define a wrapper class yourself, as long as it has

19240

an appropriate fileno() method (that really returns a file

19241

descriptor, not just a random integer).

19242

File objects on Windows are not acceptable, but sockets

19243

are.</description>

19244

<param name="iwtd" optional="0">iwtd</param><param name="owtd" optional="0">owtd</param><param name="ewtd" optional="0">ewtd</param><param name="timeout" optional="1">timeout</param>

19245

<insert>select(iwtd, owtd, ewtd, [timeout])</insert><dialog title="Insert select">select(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

19246

19247

19248

<description>The poll() system call, supported on most systems,

19249

provides better scalability for network servers that service many,

19250

many clients at the same time.

19251

poll() scales better because the system call only

19252

requires listing the file descriptors of interest, while select()

19253

builds a bitmap, turns on bits for the fds of interest, and then

19254

afterward the whole bitmap has to be linearly scanned again.

19255

select() is O(highest file descriptor), while

19256

poll() is O(number of file descriptors).

19257

</description>

19258

19259

<description>Register a file descriptor with the polling object. Future calls to

19260

the poll() method will then check whether the file descriptor

19261

has any pending I/O events. fd can be either an integer, or an

19262

object with a fileno() method that returns an integer. File

19263

objects implement

19264

fileno(), so they can also be used as the argument.

19265

eventmask is an optional bitmask describing the type of events you

19266

want to check for, and can be a combination of the constants

19267

POLLIN, POLLPRI, and POLLOUT,

19268

described in the table below. If not specified, the default value

19269

used will check for all 3 types of events.

19270

{l|l}{constant}{Constant}{Meaning}

19271

POLLIN{There is data to read}

19272

POLLPRI{There is urgent data to read}

19273

POLLOUT{Ready for output: writing will not block}

19274

POLLERR{Error condition of some sort}

19275

POLLHUP{Hung up}

19276

POLLNVAL{Invalid request: descriptor not open}

19277

Registering a file descriptor that's already registered is not an

19278

error, and has the same effect as registering the descriptor exactly

19279

once.</description>

19280

<param name="fd" optional="0">fd</param><param name="eventmask" optional="1">eventmask</param>

19281

<insert>register(fd, [eventmask])</insert><dialog title="Insert register">register(%0, %1)</dialog><info title="Info window"></info></function>

19282

19283

19284

<description>Remove a file descriptor being tracked by a polling object. Just like

19285

the register() method, fd can be an integer or an

19286

object with a fileno() method that returns an integer.

19287

Attempting to remove a file descriptor that was never registered

19288

causes a KeyError exception to be raised.</description>

19289

19290

<insert>unregister(fdfd)</insert><dialog title="Insert unregister">unregister(%0)</dialog><info title="Info window"></info></function>

19291

19292

19293

<description>Polls the set of registered file descriptors, and returns a

19294

possibly-empty list containing (fd, event) 2-tuples

19295

for the descriptors that have events or errors to report.

19296

fd is the file descriptor, and event is a bitmask

19297

with bits set for the reported events for that descriptor

19298

--- POLLIN for waiting input,

19299

POLLOUT to indicate that the descriptor can be written to, and

19300

so forth.

19301

An empty list indicates that the call timed out and no file

19302

descriptors had any events to report.

19303

If timeout is given, it specifies the length of time in

19304

milliseconds which the system will wait for events before returning.

19305

If timeout is omitted, negative, or None, the call will

19306

block until there is an event for this poll object.</description>

19307

<param name="timeout" optional="0">timeout</param>

19308

<insert>poll(timeout)</insert><dialog title="Insert poll">poll(%0)</dialog><info title="Info window"></info></function>

19309

19310

</group>

19311

</group>

19312

19313

<description>Create multiple threads of control within one interpreter.

19314

This module provides low-level primitives for working with multiple

19315

threads (a.k.a. light-weight processes or tasks) --- multiple

19316

threads of control sharing their global data space. For

19317

synchronization, simple locks (a.k.a. mutexes or binary

19318

semaphores) are provided.

19319

</description>

19320

19321

<description>Start a new thread and return its identifier. The thread executes the function

19322

function with the argument list args (which must be a tuple). The

19323

optional kwargs argument specifies a dictionary of keyword arguments.

19324

When the function returns, the thread silently exits. When the function

19325

terminates with an unhandled exception, a stack trace is printed and

19326

then the thread exits (but other threads continue to run).</description>

19327

<param name="function" optional="0">function</param><param name="args" optional="0">args</param><param name="kwargs" optional="1">kwargs</param>

19328

<insert>start_new_thread(function, args, [kwargs])</insert><dialog title="Insert start_new_thread">start_new_thread(%0, %1, %2)</dialog><info title="Info window"></info></function>

19329

19330

19331

<description>Raise a KeyboardInterrupt in the main thread. A subthread can use this

19332

function to interrupt the main thread.

19333

New in version 2.3</description>

19334

19335

<insert>interrupt_main()</insert><dialog title="Insert interrupt_main">interrupt_main()</dialog><info title="Info window"></info></function>

19336

19337

19338

<description>Raise the SystemExit exception. When not caught, this

19339

will cause the thread to exit silently.</description>

19340

19341

19342

19343

19344

<description>%Exit all threads and report the value of the integer argument

19345

%status as the exit status of the entire program.

19346

%Caveat: code in pending finally clauses, in this thread

19347

%or in other threads, is not executed.

19348

%</description>

19349

<param name="statusstatus" optional="0">statusstatus</param>

19350

<insert>exit_prog(statusstatus)</insert><dialog title="Insert exit_prog">exit_prog(%0)</dialog><info title="Info window"></info></function>

19351

19352

19353

<description>Return a new lock object. Methods of locks are described below. The

19354

lock is initially unlocked.</description>

19355

19356

<insert>allocate_lock()</insert><dialog title="Insert allocate_lock">allocate_lock()</dialog><info title="Info window"></info></function>

19357

19358

19359

<description>Return the `thread identifier' of the current thread. This is a

19360

nonzero integer. Its value has no direct meaning; it is intended as a

19361

magic cookie to be used e.g. to index a dictionary of thread-specific

19362

data. Thread identifiers may be recycled when a thread exits and

19363

another thread is created.</description>

19364

19365

<insert>get_ident()</insert><dialog title="Insert get_ident">get_ident()</dialog><info title="Info window"></info></function>

19366

19367

19368

<description>Without the optional argument, this method acquires the lock

19369

unconditionally, if necessary waiting until it is released by another

19370

thread (only one thread at a time can acquire a lock --- that's their

19371

reason for existence), and returns None. If the integer

19372

waitflag argument is present, the action depends on its

19373

value: if it is zero, the lock is only acquired if it can be acquired

19374

immediately without waiting, while if it is nonzero, the lock is

19375

acquired unconditionally as before. If an argument is present, the

19376

return value is True if the lock is acquired successfully,

19377

False if not.</description>

19378

<param name="waitflag" optional="0">waitflag</param>

19379

<insert>acquire(waitflag)</insert><dialog title="Insert acquire">acquire(%0)</dialog><info title="Info window"></info></function>

19380

19381

19382

<description>Releases the lock. The lock must have been acquired earlier, but not

19383

necessarily by the same thread.</description>

19384

19385

<insert>release()</insert><dialog title="Insert release">release()</dialog><info title="Info window"></info></function>

19386

19387

19388

<description>Return the status of the lock: True if it has been acquired by

19389

some thread, False if not.</description>

19390

19391

<insert>locked()</insert><dialog title="Insert locked">locked()</dialog><info title="Info window"></info></function>

19392

19393

</group>

19394

19395

<description>Higher-level threading interface.

19396

This module constructs higher-level threading interfaces on top of the lower level thread module.

19397

The dummy_threading module is provided for

19398

situations where threading cannot be used because

19399

thread is missing.

19400

This module defines the following functions and objects:

19401

</description>

19402

19403

<description>Return the number of currently active Thread objects.

19404

The returned count is equal to the length of the list returned by

19405

enumerate().

19406

A function that returns the number of currently active threads.</description>

19407

19408

<insert>activeCount()</insert><dialog title="Insert activeCount">activeCount()</dialog><info title="Info window"></info></function>

19409

19410

19411

<description>A factory function that returns a new condition variable object.

19412

A condition variable allows one or more threads to wait until they

19413

are notified by another thread.</description>

19414

19415

<insert>Condition()</insert><dialog title="Insert Condition">Condition()</dialog><info title="Info window"></info></function>

19416

19417

19418

<description>Return the current Thread object, corresponding to the

19419

caller's thread of control. If the caller's thread of control was not

19420

created through the

19421

threading module, a dummy thread object with limited functionality

19422

is returned.</description>

19423

19424

<insert>currentThread()</insert><dialog title="Insert currentThread">currentThread()</dialog><info title="Info window"></info></function>

19425

19426

19427

<description>Return a list of all currently active Thread objects.

19428

The list includes daemonic threads, dummy thread objects created

19429

by currentThread(), and the main thread. It excludes terminated

19430

threads and threads that have not yet been started.</description>

19431

19432

<insert>enumerate()</insert><dialog title="Insert enumerate">enumerate()</dialog><info title="Info window"></info></function>

19433

19434

19435

<description>A factory function that returns a new event object. An event manages

19436

a flag that can be set to true with the set() method and

19437

reset to false with the clear() method. The wait()

19438

method blocks until the flag is true.</description>

19439

19440

<insert>Event()</insert><dialog title="Insert Event">Event()</dialog><info title="Info window"></info></function>

19441

19442

19443

<description>A factory function that returns a new primitive lock object. Once

19444

a thread has acquired it, subsequent attempts to acquire it block,

19445

until it is released; any thread may release it.</description>

19446

19447

19448

19449

19450

<description>A factory function that returns a new reentrant lock object.

19451

A reentrant lock must be released by the thread that acquired it.

19452

Once a thread has acquired a reentrant lock, the same thread may

19453

acquire it again without blocking; the thread must release it once

19454

for each time it has acquired it.</description>

19455

19456

<insert>RLock()</insert><dialog title="Insert RLock">RLock()</dialog><info title="Info window"></info></function>

19457

19458

19459

<description>A factory function that returns a new semaphore object. A

19460

semaphore manages a counter representing the number of release()

19461

calls minus the number of acquire() calls, plus an initial value.

19462

The acquire() method blocks if necessary until it can return

19463

without making the counter negative. If not given, value defaults to

19464

1.</description>

19465

<param name="value" optional="0">value</param>

19466

<insert>Semaphore(value)</insert><dialog title="Insert Semaphore">Semaphore(%0)</dialog><info title="Info window"></info></function>

19467

19468

19469

<description>A factory function that returns a new bounded semaphore object. A bounded

19470

semaphore checks to make sure its current value doesn't exceed its initial

19471

value. If it does, ValueError is raised. In most situations

19472

semaphores are used to guard resources with limited capacity. If the

19473

semaphore is released too many times it's a sign of a bug. If not given,

19474

value defaults to 1.</description>

19475

<param name="value" optional="0">value</param>

19476

<insert>BoundedSemaphore(value)</insert><dialog title="Insert BoundedSemaphore">BoundedSemaphore(%0)</dialog><info title="Info window"></info></function>

19477

19478

19479

<description>Set a trace function</description>

19480

<param name="funcfunc" optional="0">funcfunc</param>

19481

<insert>settrace(funcfunc)</insert><dialog title="Insert settrace">settrace(%0)</dialog><info title="Info window"></info></function>

19482

19483

19484

<description>Set a profile function</description>

19485

<param name="funcfunc" optional="0">funcfunc</param>

19486

<insert>setprofile(funcfunc)</insert><dialog title="Insert setprofile">setprofile(%0)</dialog><info title="Info window"></info></function>

19487

19488

19489

<description>A primitive lock is a synchronization primitive that is not owned

19490

by a particular thread when locked. In Python, it is currently

19491

the lowest level synchronization primitive available, implemented

19492

directly by the thread extension module.

19493

A primitive lock is in one of two states, ``locked'' or ``unlocked''.

19494

It is created in the unlocked state. It has two basic methods,

19495

acquire() and release(). When the state is

19496

unlocked, acquire() changes the state to locked and returns

19497

immediately. When the state is locked, acquire() blocks

19498

until a call to release() in another thread changes it to

19499

unlocked, then the acquire() call resets it to locked and

19500

returns. The release() method should only be called in the

19501

locked state; it changes the state to unlocked and returns

19502

immediately. When more than one thread is blocked in

19503

acquire() waiting for the state to turn to unlocked, only one

19504

thread proceeds when a release() call resets the state to

19505

unlocked; which one of the waiting threads proceeds is not defined,

19506

and may vary across implementations.

19507

All methods are executed atomically.

19508

</description>

19509

19510

<description>Acquire a lock, blocking or non-blocking.

19511

When invoked without arguments, block until the lock is

19512

unlocked, then set it to locked, and return. There is no

19513

return value in this case.

19514

When invoked with the blocking argument set to true, do the

19515

same thing as when called without arguments, and return true.

19516

When invoked with the blocking argument set to false, do not

19517

block. If a call without an argument would block, return false

19518

immediately; otherwise, do the same thing as when called

19519

without arguments, and return true.</description>

19520

<param name="blocking" optional="0" default=" 1">blocking</param>

19521

<insert>acquire(blocking)</insert><dialog title="Insert acquire">acquire(%0)</dialog><info title="Info window"></info></function>

19522

19523

19524

<description>Release a lock.

19525

When the lock is locked, reset it to unlocked, and return. If

19526

any other threads are blocked waiting for the lock to become

19527

unlocked, allow exactly one of them to proceed.

19528

Do not call this method when the lock is unlocked.

19529

There is no return value.</description>

19530

19531

<insert>release()</insert><dialog title="Insert release">release()</dialog><info title="Info window"></info></function>

19532

19533

</group>

19534

19535

<description>A reentrant lock is a synchronization primitive that may be

19536

acquired multiple times by the same thread. Internally, it uses

19537

the concepts of ``owning thread'' and ``recursion level'' in

19538

addition to the locked/unlocked state used by primitive locks. In

19539

the locked state, some thread owns the lock; in the unlocked

19540

state, no thread owns it.

19541

To lock the lock, a thread calls its acquire() method; this

19542

returns once the thread owns the lock. To unlock the lock, a

19543

thread calls its release() method.

19544

acquire()/release() call pairs may be nested; only

19545

the final release() (the release() of the outermost

19546

pair) resets the lock to unlocked and allows another thread blocked in

19547

acquire() to proceed.

19548

</description>

19549

19550

<description>Acquire a lock, blocking or non-blocking.

19551

When invoked without arguments: if this thread already owns

19552

the lock, increment the recursion level by one, and return

19553

immediately. Otherwise, if another thread owns the lock,

19554

block until the lock is unlocked. Once the lock is unlocked

19555

(not owned by any thread), then grab ownership, set the

19556

recursion level to one, and return. If more than one thread

19557

is blocked waiting until the lock is unlocked, only one at a

19558

time will be able to grab ownership of the lock. There is no

19559

return value in this case.

19560

When invoked with the blocking argument set to true, do the

19561

same thing as when called without arguments, and return true.

19562

When invoked with the blocking argument set to false, do not

19563

block. If a call without an argument would block, return false

19564

immediately; otherwise, do the same thing as when called

19565

without arguments, and return true.</description>

19566

<param name="blocking" optional="0" default=" 1">blocking</param>

19567

<insert>acquire(blocking)</insert><dialog title="Insert acquire">acquire(%0)</dialog><info title="Info window"></info></function>

19568

19569

19570

<description>Release a lock, decrementing the recursion level. If after the

19571

decrement it is zero, reset the lock to unlocked (not owned by any

19572

thread), and if any other threads are blocked waiting for the lock to

19573

become unlocked, allow exactly one of them to proceed. If after the

19574

decrement the recursion level is still nonzero, the lock remains

19575

locked and owned by the calling thread.

19576

Only call this method when the calling thread owns the lock.

19577

Do not call this method when the lock is unlocked.

19578

There is no return value.</description>

19579

19580

<insert>release()</insert><dialog title="Insert release">release()</dialog><info title="Info window"></info></function>

19581

19582

</group>

19583

19584

<description>A condition variable is always associated with some kind of lock;

19585

this can be passed in or one will be created by default. (Passing

19586

one in is useful when several condition variables must share the

19587

same lock.)

19588

A condition variable has acquire() and release()

19589

methods that call the corresponding methods of the associated lock.

19590

It also has a wait() method, and notify() and

19591

notifyAll() methods. These three must only be called when

19592

the calling thread has acquired the lock.

19593

The wait() method releases the lock, and then blocks until it

19594

is awakened by a notify() or notifyAll() call for

19595

the same condition variable in another thread. Once awakened, it

19596

re-acquires the lock and returns. It is also possible to specify a

19597

timeout.

19598

The notify() method wakes up one of the threads waiting for

19599

the condition variable, if any are waiting. The notifyAll()

19600

method wakes up all threads waiting for the condition variable.

19601

Note: the notify() and notifyAll() methods don't

19602

release the lock; this means that the thread or threads awakened will

19603

not return from their wait() call immediately, but only when

19604

the thread that called notify() or notifyAll()

19605

finally relinquishes ownership of the lock.

19606

Tip: the typical programming style using condition variables uses the

19607

lock to synchronize access to some shared state; threads that are

19608

interested in a particular change of state call wait()

19609

repeatedly until they see the desired state, while threads that modify

19610

the state call notify() or notifyAll() when they

19611

change the state in such a way that it could possibly be a desired

19612

state for one of the waiters. For example, the following code is a

19613

generic producer-consumer situation with unlimited buffer capacity:

19614

# Consume one item

19615

cv.acquire()

19616

while not an_item_is_available():

19617

cv.wait()

19618

get_an_available_item()

19619

cv.release()

19620

# Produce one item

19621

cv.acquire()

19622

make_an_item_available()

19623

cv.notify()

19624

cv.release()

19625

To choose between notify() and notifyAll(), consider

19626

whether one state change can be interesting for only one or several

19627

waiting threads. E.g. in a typical producer-consumer situation,

19628

adding one item to the buffer only needs to wake up one consumer

19629

thread.

19630

</description>

19631

19632

<description>If the lock argument is given and not None, it must be a

19633

Lock or RLock object, and it is used as the underlying

19634

lock. Otherwise, a new RLock object is created and used as

19635

the underlying lock.</description>

19636

19637

<insert>Condition(lock)</insert><dialog title="Insert Condition">Condition(%0)</dialog><info title="Info window"></info></function>

19638

19639

19640

<description>Acquire the underlying lock.

19641

This method calls the corresponding method on the underlying

19642

lock; the return value is whatever that method returns.</description>

19643

19644

<insert>acquire(*args*args)</insert><dialog title="Insert acquire">acquire(%0)</dialog><info title="Info window"></info></function>

19645

19646

19647

<description>Release the underlying lock.

19648

This method calls the corresponding method on the underlying

19649

lock; there is no return value.</description>

19650

19651

<insert>release()</insert><dialog title="Insert release">release()</dialog><info title="Info window"></info></function>

19652

19653

19654

<description>Wait until notified or until a timeout occurs.

19655

This must only be called when the calling thread has acquired the

19656

lock.

19657

This method releases the underlying lock, and then blocks until it is

19658

awakened by a notify() or notifyAll() call for the

19659

same condition variable in another thread, or until the optional

19660

timeout occurs. Once awakened or timed out, it re-acquires the lock

19661

and returns.

19662

When the timeout argument is present and not None, it

19663

should be a floating point number specifying a timeout for the

19664

operation in seconds (or fractions thereof).

19665

When the underlying lock is an RLock, it is not released using

19666

its release() method, since this may not actually unlock the

19667

lock when it was acquired multiple times recursively. Instead, an

19668

internal interface of the RLock class is used, which really

19669

unlocks it even when it has been recursively acquired several times.

19670

Another internal interface is then used to restore the recursion level

19671

when the lock is reacquired.</description>

19672

<param name="timeout" optional="0">timeout</param>

19673

<insert>wait(timeout)</insert><dialog title="Insert wait">wait(%0)</dialog><info title="Info window"></info></function>

19674

19675

19676

<description>Wake up a thread waiting on this condition, if any.

19677

This must only be called when the calling thread has acquired the

19678

lock.

19679

This method wakes up one of the threads waiting for the condition

19680

variable, if any are waiting; it is a no-op if no threads are waiting.

19681

The current implementation wakes up exactly one thread, if any are

19682

waiting. However, it's not safe to rely on this behavior. A future,

19683

optimized implementation may occasionally wake up more than one

19684

thread.

19685

Note: the awakened thread does not actually return from its

19686

wait() call until it can reacquire the lock. Since

19687

notify() does not release the lock, its caller should.</description>

19688

19689

<insert>notify()</insert><dialog title="Insert notify">notify()</dialog><info title="Info window"></info></function>

19690

19691

19692

<description>Wake up all threads waiting on this condition. This method acts like

19693

notify(), but wakes up all waiting threads instead of one.</description>

19694

19695

<insert>notifyAll()</insert><dialog title="Insert notifyAll">notifyAll()</dialog><info title="Info window"></info></function>

19696

19697

</group>

19698

19699

<description>This is one of the oldest synchronization primitives in the history of

19700

computer science, invented by the early Dutch computer scientist

19701

Edsger W. Dijkstra (he used P() and V() instead of

19702

acquire() and release()).

19703

A semaphore manages an internal counter which is decremented by each

19704

acquire() call and incremented by each release()

19705

call. The counter can never go below zero; when acquire()

19706

finds that it is zero, it blocks, waiting until some other thread

19707

calls release().

19708

</description>

19709

19710

<description>The optional argument gives the initial value for the internal

19711

counter; it defaults to 1.</description>

19712

<param name="value" optional="0">value</param>

19713

<insert>Semaphore(value)</insert><dialog title="Insert Semaphore">Semaphore(%0)</dialog><info title="Info window"></info></function>

19714

19715

19716

<description>Acquire a semaphore.

19717

When invoked without arguments: if the internal counter is larger than

19718

zero on entry, decrement it by one and return immediately. If it is

19719

zero on entry, block, waiting until some other thread has called

19720

release() to make it larger than zero. This is done with

19721

proper interlocking so that if multiple acquire() calls are

19722

blocked, release() will wake exactly one of them up. The

19723

implementation may pick one at random, so the order in which blocked

19724

threads are awakened should not be relied on. There is no return

19725

value in this case.

19726

When invoked with blocking set to true, do the same thing as

19727

when called without arguments, and return true.

19728

When invoked with blocking set to false, do not block. If a

19729

call without an argument would block, return false immediately;

19730

otherwise, do the same thing as when called without arguments, and

19731

return true.</description>

19732

<param name="blocking" optional="0">blocking</param>

19733

<insert>acquire(blocking)</insert><dialog title="Insert acquire">acquire(%0)</dialog><info title="Info window"></info></function>

19734

19735

19736

<description>Release a semaphore,

19737

incrementing the internal counter by one. When it was zero on

19738

entry and another thread is waiting for it to become larger

19739

than zero again, wake up that thread.</description>

19740

19741

<insert>release()</insert><dialog title="Insert release">release()</dialog><info title="Info window"></info></function>

19742

19743

</group>

19744

19745

<description>This is one of the simplest mechanisms for communication between

19746

threads: one thread signals an event and other threads wait for it.

19747

An event object manages an internal flag that can be set to true with

19748

the set() method and reset to false with the clear()

19749

method. The wait() method blocks until the flag is true.

19750

</description>

19751

19752

<description>The internal flag is initially false.</description>

19753

19754

<insert>Event()</insert><dialog title="Insert Event">Event()</dialog><info title="Info window"></info></function>

19755

19756

19757

<description>Return true if and only if the internal flag is true.</description>

19758

19759

<insert>isSet()</insert><dialog title="Insert isSet">isSet()</dialog><info title="Info window"></info></function>

19760

19761

19762

<description>Set the internal flag to true.

19763

All threads waiting for it to become true are awakened.

19764

Threads that call wait() once the flag is true will not block

19765

at all.</description>

19766

19767

19768

19769

19770

<description>Reset the internal flag to false.

19771

Subsequently, threads calling wait() will block until

19772

set() is called to set the internal flag to true again.</description>

19773

19774

<insert>clear()</insert><dialog title="Insert clear">clear()</dialog><info title="Info window"></info></function>

19775

19776

19777

<description>Block until the internal flag is true.

19778

If the internal flag is true on entry, return immediately. Otherwise,

19779

block until another thread calls set() to set the flag to

19780

true, or until the optional timeout occurs.

19781

When the timeout argument is present and not None, it should be a

19782

floating point number specifying a timeout for the operation in

19783

seconds (or fractions thereof).</description>

19784

<param name="timeout" optional="0">timeout</param>

19785

<insert>wait(timeout)</insert><dialog title="Insert wait">wait(%0)</dialog><info title="Info window"></info></function>

19786

19787

</group>

19788

19789

<description>This class represents an activity that is run in a separate thread

19790

of control. There are two ways to specify the activity: by

19791

passing a callable object to the constructor, or by overriding the

19792

run() method in a subclass. No other methods (except for the

19793

constructor) should be overridden in a subclass. In other words, only override the __init__() and run()

19794

methods of this class.

19795

Once a thread object is created, its activity must be started by

19796

calling the thread's start() method. This invokes the

19797

run() method in a separate thread of control.

19798

Once the thread's activity is started, the thread is considered

19799

'alive' and 'active' (these concepts are almost, but not quite

19800

exactly, the same; their definition is intentionally somewhat

19801

vague). It stops being alive and active when its run()

19802

method terminates -- either normally, or by raising an unhandled

19803

exception. The isAlive() method tests whether the thread is

19804

alive.

19805

Other threads can call a thread's join() method. This blocks

19806

the calling thread until the thread whose join() method is

19807

called is terminated.

19808

A thread has a name. The name can be passed to the constructor,

19809

set with the setName() method, and retrieved with the

19810

getName() method.

19811

A thread can be flagged as a ``daemon thread''. The significance

19812

of this flag is that the entire Python program exits when only

19813

daemon threads are left. The initial value is inherited from the

19814

creating thread. The flag can be set with the setDaemon()

19815

method and retrieved with the isDaemon() method.

19816

There is a ``main thread'' object; this corresponds to the

19817

initial thread of control in the Python program. It is not a

19818

daemon thread.

19819

There is the possibility that ``dummy thread objects'' are

19820

created. These are thread objects corresponding to ``alien

19821

threads''. These are threads of control started outside the

19822

threading module, such as directly from C code. Dummy thread objects

19823

have limited functionality; they are always considered alive,

19824

active, and daemonic, and cannot be join()ed. They are never deleted, since it is impossible to detect the termination of alien

19825

threads.

19826

</description>

19827

19828

<description>This constructor should always be called with keyword

19829

arguments. Arguments are:

19830

group should be None; reserved for future extension when

19831

a ThreadGroup class is implemented.

19832

target is the callable object to be invoked by the

19833

run() method. Defaults to None, meaning nothing is

19834

called.

19835

name is the thread name. By default, a unique name is

19836

constructed of the form ``Thread-N'' where N is a small

19837

decimal number.

19838

args is the argument tuple for the target invocation. Defaults

19839

to ().

19840

kwargs is a dictionary of keyword arguments for the target

19841

invocation. Defaults to {}.

19842

If the subclass overrides the constructor, it must make sure

19843

to invoke the base class constructor (Thread.__init__())

19844

before doing anything else to the thread.</description>

19845

<param name="group" optional="0" default="None">group</param><param name="target" optional="0" default="None">target</param><param name="name" optional="0" default="None">name</param><param name="args" optional="0" default="()">args</param><param name="kwargs" optional="0">kwargs</param>

19846

<insert>Thread(group, target, name, args, kwargs)</insert><dialog title="Insert Thread">Thread(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

19847

19848

19849

<description>Start the thread's activity.

19850

This must be called at most once per thread object. It

19851

arranges for the object's run() method to be invoked in a

19852

separate thread of control.</description>

19853

19854

<insert>start()</insert><dialog title="Insert start">start()</dialog><info title="Info window"></info></function>

19855

19856

19857

<description>Method representing the thread's activity.

19858

You may override this method in a subclass. The standard

19859

run() method invokes the callable object passed to the

19860

object's constructor as the target argument, if any, with

19861

sequential and keyword arguments taken from the args and

19862

kwargs arguments, respectively.</description>

19863

19864

19865

19866

19867

<description>Wait until the thread terminates.

19868

This blocks the calling thread until the thread whose join()

19869

method is called terminates -- either normally or through an

19870

unhandled exception -- or until the optional timeout occurs.

19871

When the timeout argument is present and not None, it

19872

should be a floating point number specifying a timeout for the

19873

operation in seconds (or fractions thereof).

19874

A thread can be join()ed many times.

19875

A thread cannot join itself because this would cause a

19876

deadlock.

19877

It is an error to attempt to join() a thread before it has

19878

been started.</description>

19879

<param name="timeout" optional="0">timeout</param>

19880

<insert>join(timeout)</insert><dialog title="Insert join">join(%0)</dialog><info title="Info window"></info></function>

19881

19882

19883

<description>Return the thread's name.</description>

19884

19885

<insert>getName()</insert><dialog title="Insert getName">getName()</dialog><info title="Info window"></info></function>

19886

19887

19888

<description>Set the thread's name.

19889

The name is a string used for identification purposes only.

19890

It has no semantics. Multiple threads may be given the same

19891

name. The initial name is set by the constructor.</description>

19892

<param name="namename" optional="0">namename</param>

19893

<insert>setName(namename)</insert><dialog title="Insert setName">setName(%0)</dialog><info title="Info window"></info></function>

19894

19895

19896

<description>Return whether the thread is alive.

19897

Roughly, a thread is alive from the moment the start() method

19898

returns until its run() method terminates.</description>

19899

19900

<insert>isAlive()</insert><dialog title="Insert isAlive">isAlive()</dialog><info title="Info window"></info></function>

19901

19902

19903

<description>Return the thread's daemon flag.</description>

19904

19905

<insert>isDaemon()</insert><dialog title="Insert isDaemon">isDaemon()</dialog><info title="Info window"></info></function>

19906

19907

19908

<description>Set the thread's daemon flag to the Boolean value daemonic.

19909

This must be called before start() is called.

19910

The initial value is inherited from the creating thread.

19911

The entire Python program exits when no active non-daemon

19912

threads are left.</description>

19913

<param name="daemonicdaemonic" optional="0">daemonicdaemonic</param>

19914

<insert>setDaemon(daemonicdaemonic)</insert><dialog title="Insert setDaemon">setDaemon(%0)</dialog><info title="Info window"></info></function>

19915

19916

</group>

19917

19918

<description>This class represents an action that should be run only after a

19919

certain amount of time has passed --- a timer. Timer is a

19920

subclass of Thread and as such also functions as an example of

19921

creating custom threads.

19922

Timers are started, as with threads, by calling their start()

19923

method. The timer can be stopped (before its action has begun) by

19924

calling the cancel() method. The interval the timer will

19925

wait before executing its action may not be exactly the same as the

19926

interval specified by the user.

19927

For example:

19928

def hello():

19929

print "hello, world"

19930

t = Timer(30.0, hello)

19931

t.start() # after 30 seconds, "hello, world" will be printed

19932

</description>

19933

19934

<description>Create a timer that will run function with arguments args and keyword arguments kwargs, after interval seconds have passed.</description>

19935

<param name="interval" optional="0">interval</param><param name="function" optional="0">function</param><param name="args" optional="0" default="[]">args</param><param name="kwargs" optional="0">kwargs</param>

19936

<insert>Timer(interval, function, args, kwargs)</insert><dialog title="Insert Timer">Timer(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

19937

19938

19939

<description>Stop the timer, and cancel the execution of the timer's action. This

19940

will only work if the timer is still in its waiting stage.</description>

19941

19942

<insert>cancel()</insert><dialog title="Insert cancel">cancel()</dialog><info title="Info window"></info></function>

19943

19944

</group>

19945

</group>

19946

19947

</group>

19948

19949

</group>

19950

19951

<description>A synchronized queue class.

19952

The Queue module implements a multi-producer, multi-consumer

19953

FIFO queue. It is especially useful in threads programming when

19954

information must be exchanged safely between multiple threads. The

19955

Queue class in this module implements all the required locking

19956

semantics. It depends on the availability of thread support in

19957

Python.

19958

bisect{PriorityQueue example using the Queue class}

19959

The Queue module defines the following class and exception:

19960

</description>

19961

19962

<description>Constructor for the class. maxsize is an integer that sets the

19963

upperbound limit on the number of items that can be placed in the

19964

queue. Insertion will block once this size has been reached, until

19965

queue items are consumed. If maxsize is less than or equal to

19966

zero, the queue size is infinite.</description>

19967

<param name="maxsizemaxsize" optional="0">maxsizemaxsize</param>

19968

<insert>Queue(maxsizemaxsize)</insert><dialog title="Insert Queue">Queue(%0)</dialog><info title="Info window"></info></function>

19969

19970

19971

19972

<description>Return the approximate size of the queue. Because of multithreading

19973

semantics, this number is not reliable.</description>

19974

19975

<insert>qsize()</insert><dialog title="Insert qsize">qsize()</dialog><info title="Info window"></info></function>

19976

19977

19978

<description>Return True if the queue is empty, False otherwise.

19979

Becauseof multithreading semantics, this is not reliable.</description>

19980

19981

<insert>empty()</insert><dialog title="Insert empty">empty()</dialog><info title="Info window"></info></function>

19982

19983

19984

<description>Return True if the queue is full, False otherwise.

19985

Because of multithreading semantics, this is not reliable.</description>

19986

19987

19988

19989

19990

<description>Put item into the queue. If optional args block is true

19991

and timeout is None (the default), block if necessary until a

19992

free slot is available. If timeout is a positive number, it

19993

blocks at most timeout seconds and raises the Full

19994

exception if no free slot was available within that time.

19995

Otherwise (block is false), put an item on the queue if a free

19996

slot is immediately available, else raise the Full

19997

exception (timeout is ignored in that case).

19998

New in version 2.3</description>

19999

<param name="item" optional="0">item</param><param name="block" optional="1">block</param><param name="timeout" optional="1">timeout</param>

20000

<insert>put(item, [block], [timeout])</insert><dialog title="Insert put">put(%0, %1, %2)</dialog><info title="Info window"></info></function>

20001

20002

20003

<description>Equivalent to put(item, False).</description>

20004

<param name="itemitem" optional="0">itemitem</param>

20005

<insert>put_nowait(itemitem)</insert><dialog title="Insert put_nowait">put_nowait(%0)</dialog><info title="Info window"></info></function>

20006

20007

20008

<description>Remove and return an item from the queue. If optional args

20009

block is true and timeout is None (the default),

20010

block if necessary until an item is available. If timeout is

20011

a positive number, it blocks at most timeout seconds and raises

20012

the Empty exception if no item was available within that

20013

time. Otherwise (block is false), return an item if one is

20014

immediately available, else raise the Empty exception

20015

(timeout is ignored in that case).

20016

New in version 2.3</description>

20017

<param name="block" optional="0">block</param><param name="timeout" optional="1">timeout</param>

20018

<insert>get(block, [timeout])</insert><dialog title="Insert get">get(%0, %1)</dialog><info title="Info window"></info></function>

20019

20020

20021

<description>Equivalent to get(False).</description>

20022

20023

<insert>get_nowait()</insert><dialog title="Insert get_nowait">get_nowait()</dialog><info title="Info window"></info></function>

20024

20025

</group>

20026

</group>

20027

20028

<description>Interface to memory-mapped files for Windows.

20029

Memory-mapped file objects behave like both strings and like

20030

file objects. Unlike normal string objects, however, these are

20031

mutable. You can use mmap objects in most places where strings

20032

are expected; for example, you can use the re module to

20033

search through a memory-mapped file. Since they're mutable, you can

20034

change a single character by doing obj[index] = 'a', or

20035

change a substring by assigning to a slice:

20036

obj[i1:i2] = '...'. You can also read and write

20037

data starting at the current file position, and seek()

20038

through the file to different positions.

20039

A memory-mapped file is created by the mmap() function,

20040

which is different on and on Windows. In either case you must

20041

provide a file descriptor for a file opened for update.

20042

If you wish to map an existing Python file object, use its

20043

fileno() method to obtain the correct value for the

20044

fileno parameter. Otherwise, you can open the file using the

20045

os.open() function, which returns a file descriptor

20046

directly (the file still needs to be closed when done).

20047

For both the and Windows versions of the function,

20048

access may be specified as an optional keyword parameter.

20049

access accepts one of three values: ACCESS_READ,

20050

ACCESS_WRITE, or ACCESS_COPY to specify

20051

readonly, write-through or copy-on-write memory respectively.

20052

access can be used on both and Windows. If

20053

access is not specified, Windows mmap returns a write-through

20054

mapping. The initial memory values for all three access types are

20055

taken from the specified file. Assignment to an

20056

ACCESS_READ memory map raises a TypeError

20057

exception. Assignment to an ACCESS_WRITE memory map

20058

affects both memory and the underlying file. Assigment to an

20059

ACCESS_COPY memory map affects memory but does not update

20060

the underlying file.

20061

</description>

20062

20063

<description>(Windows version) Maps length bytes from the file

20064

specified by the file handle fileno, and returns a mmap

20065

object. If length is 0, the maximum length of the map

20066

will be the current size of the file when mmap() is

20067

called.

20068

tagname, if specified and not None, is a string giving

20069

a tag name for the mapping. Windows allows you to have many

20070

different mappings against the same file. If you specify the name

20071

of an existing tag, that tag is opened, otherwise a new tag of this

20072

name is created. If this parameter is omitted or None, the

20073

mapping is created without a name. Avoiding the use of the tag

20074

parameter will assist in keeping your code portable between and Windows.</description>

20075

<param name="fileno" optional="0">fileno</param><param name="length" optional="0">length</param><param name="tagname" optional="1">tagname</param><param name="access" optional="1">access</param>

20076

<insert>mmap(fileno, length, [tagname], [access])</insert><dialog title="Insert mmap">mmap(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

20077

20078

20079

<description>Close the file. Subsequent calls to other methods of the object

20080

will result in an exception being raised.</description>

20081

20082

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

20083

20084

20085

<description>Returns the lowest index in the object where the substring

20086

string is found. Returns -1 on failure. start

20087

is the index at which the search begins, and defaults to zero.</description>

20088

<param name="string" optional="0">string</param><param name="start" optional="1">start</param>

20089

<insert>find(string, [start])</insert><dialog title="Insert find">find(%0, %1)</dialog><info title="Info window"></info></function>

20090

20091

20092

<description>Flushes changes made to the in-memory copy of a file back to disk.

20093

Without use of this call there is no guarantee that changes are

20094

written back before the object is destroyed. If offset and

20095

size are specified, only changes to the given range of bytes

20096

will be flushed to disk; otherwise, the whole extent of the mapping

20097

is flushed.</description>

20098

<param name="offset" optional="0">offset</param><param name="size" optional="1">size</param>

20099

<insert>flush(offset, [size])</insert><dialog title="Insert flush">flush(%0, %1)</dialog><info title="Info window"></info></function>

20100

20101

20102

<description>Copy the count bytes starting at offset src to the

20103

destination index dest. If the mmap was created with

20104

ACCESS_READ, then calls to move will throw a

20105

TypeError exception.</description>

20106

<param name="dest" optional="0">dest</param><param name="src" optional="0">src</param><param name="count" optional="0">count</param>

20107

<insert>move(dest, src, count)</insert><dialog title="Insert move">move(%0, %1, %2)</dialog><info title="Info window"></info></function>

20108

20109

20110

<description>Return a string containing up to num bytes starting from the

20111

current file position; the file position is updated to point after the

20112

bytes that were returned.</description>

20113

20114

20115

20116

20117

<description>Returns a string of length 1 containing the character at the current

20118

file position, and advances the file position by 1.</description>

20119

20120

20121

20122

20123

<description>Returns a single line, starting at the current file position and up to the next newline.</description>

20124

20125

<insert>readline()</insert><dialog title="Insert readline">readline()</dialog><info title="Info window"></info></function>

20126

20127

20128

<description>If the mmap was created with ACCESS_READ or

20129

ACCESS_COPY, resizing the map will throw a TypeError exception.</description>

20130

<param name="newsize" optional="0">newsize</param>

20131

<insert>resize(newsize)</insert><dialog title="Insert resize">resize(%0)</dialog><info title="Info window"></info></function>

20132

20133

20134

<description>Set the file's current position. whence argument is optional

20135

and defaults to 0 (absolute file positioning); other values

20136

are 1 (seek relative to the current position) and 2

20137

(seek relative to the file's end).</description>

20138

<param name="pos" optional="0">pos</param><param name="whence" optional="1">whence</param>

20139

<insert>seek(pos, [whence])</insert><dialog title="Insert seek">seek(%0, %1)</dialog><info title="Info window"></info></function>

20140

20141

20142

<description>Return the length of the file, which can be larger than the size of

20143

the memory-mapped area.</description>

20144

20145

20146

20147

20148

<description>Returns the current position of the file pointer.</description>

20149

20150

20151

20152

20153

<description>Write the bytes in string into memory at the current position

20154

of the file pointer; the file position is updated to point after the

20155

bytes that were written. If the mmap was created with

20156

ACCESS_READ, then writing to it will throw a

20157

TypeError exception.</description>

20158

<param name="string" optional="0">string</param>

20159

<insert>write(string)</insert><dialog title="Insert write">write(%0)</dialog><info title="Info window"></info></function>

20160

20161

20162

<description>Write the single-character string byte into memory at the

20163

current position of the file pointer; the file position is advanced

20164

by 1.If the mmap was created with ACCESS_READ,

20165

then writing to it will throw a TypeError exception.</description>

20166

20167

<insert>write_byte(byte)</insert><dialog title="Insert write_byte">write_byte(%0)</dialog><info title="Info window"></info></function>

20168

20169

</group>

20170

20171

<description>Generic interface to DBM-style database modules.

20172

anydbm is a generic interface to variants of the DBM

20173

database --- dbhashdbhash (requires

20174

bsddbbsddb),

20175

gdbmgdbm, or

20176

dbmdbm. If none of these modules is

20177

installed, the slow-but-simple implementation in module

20178

dumbdbmdumbdbm will be used.

20179

</description>

20180

20181

<description>Open the database file filename and return a corresponding object.

20182

If the database file already exists, the whichdb module is used to determine its type and the appropriate module is used; if it

20183

does not exist, the first module listed above that can be imported is

20184

used.

20185

The optional flag argument can be

20186

'r' to open an existing database for reading only,

20187

'w' to open an existing database for reading and writing,

20188

'c' to create the database if it doesn't exist, or

20189

'n', which will always create a new empty database. If not

20190

specified, the default value is 'r'.

20191

The optional mode argument is the mode of the file, used

20192

only when the database has to be created. It defaults to octal

20193

0666 (and will be modified by the prevailing umask).</description>

20194

<param name="filename" optional="0">filename</param><param name="flag" optional="1">flag</param><param name="mode" optional="1">mode</param>

20195

<insert>open(filename, [flag], [mode])</insert><dialog title="Insert open">open(%0, %1, %2)</dialog><info title="Info window"></info></function>

20196

20197

</group>

20198

20199

<description>Unix, Windows

20200

DBM-style interface to the BSD database library.

20201

The dbhash module provides a function to open databases using

20202

the BSD db library. This module mirrors the interface of the

20203

other Python database modules that provide access to DBM-style

20204

databases. The bsddbbsddb module is required to use dbhash.

20205

This module provides an exception and a function:

20206

{error}

20207

Exception raised on database errors other than

20208

KeyError. It is a synonym for bsddb.error.

20209

</description>

20210

20211

<description>Open a db database and return the database object. The

20212

path argument is the name of the database file.

20213

The flag argument can be

20214

'r' (the default), 'w',

20215

'c' (which creates the database if it doesn't exist), or

20216

'n' (which always creates a new empty database).

20217

For platforms on which the BSD db library supports locking,

20218

an l can be appended to indicate that locking should be

20219

used.

20220

The optional mode parameter is used to indicate the permission bits that should be set if a new database must be

20221

created; this will be masked by the current umask value for the

20222

process.</description>

20223

20224

20225

20226

20227

<description>The database objects returned by open() provide the methods common to all the DBM-style databases and mapping objects. The following

20228

methods are available in addition to the standard methods.

20229

</description>

20230

20231

<description>It's possible to loop over every key/value pair in the database using

20232

this method and the next() method. The traversal is ordered by

20233

the databases internal hash values, and won't be sorted by the key

20234

values. This method returns the starting key.</description>

20235

20236

<insert>first()</insert><dialog title="Insert first">first()</dialog><info title="Info window"></info></function>

20237

20238

20239

<description>Return the last key/value pair in a database traversal. This may be used to

20240

begin a reverse-order traversal; see previous().</description>

20241

20242

20243

20244

20245

<description>Returns the key next key/value pair in a database traversal. The

20246

following code prints every key in the database db, without

20247

having to create a list in memory that contains them all:

20248

print db.first()

20249

for i in xrange(1, len(db)):

20250

print db.next()

20251

</description>

20252

20253

20254

20255

20256

<description>Returns the previous key/value pair in a forward-traversal of the database.

20257

In conjunction with last(), this may be used to implement

20258

a reverse-order traversal.</description>

20259

20260

<insert>previous()</insert><dialog title="Insert previous">previous()</dialog><info title="Info window"></info></function>

20261

20262

20263

<description>This method forces any unwritten data to be written to the disk.</description>

20264

20265

20266

20267

</group>

20268

</group>

20269

20270

<description>Guess which DBM-style module created a given database.

20271

The single function in this module attempts to guess which of the

20272

several simple database modules available--dbm,

20273

gdbm, or dbhash--should be used to open a

20274

given file.

20275

</description>

20276

20277

<description>Returns one of the following values: None if the file can't be

20278

opened because it's unreadable or doesn't exist; the empty string

20279

('') if the file's format can't be guessed; or a string

20280

containing the required module name, such as 'dbm' or

20281

'gdbm'.</description>

20282

<param name="filenamefilename" optional="0">filenamefilename</param>

20283

<insert>whichdb(filenamefilename)</insert><dialog title="Insert whichdb">whichdb(%0)</dialog><info title="Info window"></info></function>

20284

20285

</group>

20286

20287

<description>Unix, Windows

20288

Interface to Berkeley DB database library

20289

The bsddb module provides an interface to the Berkeley DB

20290

library. Users can create hash, btree or record based library files

20291

using the appropriate open call. Bsddb objects behave generally like

20292

dictionaries. Keys and values must be strings, however, so to use

20293

other objects as keys or to store other kinds of objects the user must

20294

serialize them somehow, typically using marshal.dumps or pickle.dumps.

20295

Starting with Python 2.3 the bsddb module requires the

20296

Berkeley DB library version 3.2 or later (it is known to work with 3.2

20297

thru 4.2 at the time of this writing).

20298

http://pybsddb.sourceforge.net/{Website with documentation

20299

for the new python Berkeley DB interface that closely mirrors the sleepycat object oriented interface provided in Berkeley DB 3 and 4.}

20300

http://www.sleepycat.com/{Sleepycat Software produces the

20301

modern Berkeley DB library.}

20302

The following is a description of the legacy bsddb interface

20303

compatible with the old python bsddb module. For details about the more

20304

modern Db and DbEnv object oriented interface see the above mentioned

20305

pybsddb URL.

20306

The bsddb module defines the following functions that create

20307

objects that access the appropriate type of Berkeley DB file. The

20308

first two arguments of each function are the same. For ease of

20309

portability, only the first two arguments should be used in most

20310

instances.

20311

</description>

20312

20313

<description>Open the hash format file named filename. Files never intended

20314

to be preserved on disk may be created by passing None as the filename. The optional

20315

flag identifies the mode used to open the file. It may be

20316

r (read only, default), w (read-write) ,

20317

c (read-write - create if necessary) or

20318

n (read-write - truncate to zero length). The other

20319

arguments are rarely used and are just passed to the low-level

20320

dbopen() function. Consult the Berkeley DB documentation

20321

for their use and interpretation.</description>

20322

<param name="filename" optional="0">filename</param><param name="flag" optional="1">flag</param><param name="mode" optional="1">mode</param><param name="bsize" optional="1">bsize</param><param name="ffactor" optional="1">ffactor</param><param name="nelem" optional="1">nelem</param><param name="cachesize" optional="1">cachesize</param><param name="hash" optional="1">hash</param><param name="lorder" optional="1">lorder</param>

20323

<insert>hashopen(filename, [flag], [mode], [bsize], [ffactor], [nelem], [cachesize], [hash], [lorder])</insert><dialog title="Insert hashopen">hashopen(%0, %1, %2, %3, %4, %5, %6, %7, %8)</dialog><info title="Info window"></info></function>

20324

20325

20326

<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

20327

flag identifies the mode used to open the file. It may be

20328

r (read only, default), w (read-write),

20329

c (read-write - create if necessary) or

20330

n (read-write - truncate to zero length). The other

20331

arguments are rarely used and are just passed to the low-level dbopen

20332

function. Consult the Berkeley DB documentation for their use and

20333

interpretation.</description>

20334

<param name="filename" optional="0">filename</param><param name="flag" optional="1">flag</param><param name="mode" optional="1">mode</param><param name="btflags" optional="1">btflags</param><param name="cachesize" optional="1">cachesize</param><param name="maxkeypage" optional="1">maxkeypage</param><param name="minkeypage" optional="1">minkeypage</param><param name="psize" optional="1">psize</param><param name="lorder" optional="1">lorder</param>

20335

<insert>btopen(filename, [flag], [mode], [btflags], [cachesize], [maxkeypage], [minkeypage], [psize], [lorder])</insert><dialog title="Insert btopen">btopen(%0, %1, %2, %3, %4, %5, %6, %7, %8)</dialog><info title="Info window"></info></function>

20336

20337

20338

<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

20339

flag identifies the mode used to open the file. It may be

20340

r (read only, default), w (read-write),

20341

c (read-write - create if necessary) or

20342

n (read-write - truncate to zero length). The other

20343

arguments are rarely used and are just passed to the low-level dbopen

20344

function. Consult the Berkeley DB documentation for their use and

20345

interpretation.</description>

20346

<param name="filename" optional="0">filename</param><param name="flag" optional="1">flag</param><param name="mode" optional="1">mode</param><param name="rnflags" optional="1">rnflags</param><param name="cachesize" optional="1">cachesize</param><param name="psize" optional="1">psize</param><param name="lorder" optional="1">lorder</param><param name="reclen" optional="1">reclen</param><param name="bval" optional="1">bval</param><param name="bfname" optional="1">bfname</param>

20347

<insert>rnopen(filename, [flag], [mode], [rnflags], [cachesize], [psize], [lorder], [reclen], [bval], [bfname])</insert><dialog title="Insert rnopen">rnopen(%0, %1, %2, %3, %4, %5, %6, %7, %8, %9)</dialog><info title="Info window"></info></function>

20348

20349

20350

<description>Once instantiated, hash, btree and record objects support

20351

the same methods as dictionaries. In addition, they support

20352

the methods listed below.

20353

Changed in version 2.3.1: Added dictionary methods

20354

</description>

20355

20356

<description>Close the underlying file. The object can no longer be accessed. Since

20357

there is no open open method for these objects, to open the file

20358

again a new bsddb module open function must be called.</description>

20359

20360

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

20361

20362

20363

<description>Return the list of keys contained in the DB file. The order of the list is

20364

unspecified and should not be relied on. In particular, the order of the

20365

list returned is different for different file formats.</description>

20366

20367

20368

20369

20370

<description>Return 1 if the DB file contains the argument as a key.</description>

20371

<param name="keykey" optional="0">keykey</param>

20372

<insert>has_key(keykey)</insert><dialog title="Insert has_key">has_key(%0)</dialog><info title="Info window"></info></function>

20373

20374

20375

<description>Set the cursor to the item indicated by key and return a tuple

20376

containing the key and its value. For binary tree databases (opened

20377

using btopen()), if key does not actually exist in

20378

the database, the cursor will point to the next item in sorted order

20379

and return that key and value. For other databases,

20380

KeyError will be raised if key is not found in the

20381

database.</description>

20382

<param name="keykey" optional="0">keykey</param>

20383

<insert>set_location(keykey)</insert><dialog title="Insert set_location">set_location(%0)</dialog><info title="Info window"></info></function>

20384

20385

20386

<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>

20387

20388

<insert>first()</insert><dialog title="Insert first">first()</dialog><info title="Info window"></info></function>

20389

20390

20391

<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>

20392

20393

20394

20395

20396

<description>Set the cursor to the previous item in the DB file and return it. The

20397

order of keys in the file is unspecified, except in the case of B-Tree

20398

databases. This is not supported on hashtable databases (those opened

20399

with hashopen()).</description>

20400

20401

<insert>previous()</insert><dialog title="Insert previous">previous()</dialog><info title="Info window"></info></function>

20402

20403

20404

<description>Set the cursor to the last item in the DB file and return it. The

20405

order of keys in the file is unspecified. This is not supported on

20406

hashtable databases (those opened with hashopen()).</description>

20407

20408

20409

20410

20411

<description>Synchronize the database on disk.</description>

20412

20413

20414

20415

</group>

20416

</group>

20417

20418

<description>Portable implementation of the simple DBM interface.

20419

</description>

20420

20421

<description>Open a dumbdbm database and return a dumbdbm object. The filename

20422

argument is the basename of the database file (without any specific

20423

extensions). When a dumbdbm database is created, files with .dat and

20424

.dir extensions are created.

20425

The optional flag argument is currently ignored; the database is

20426

always opened for update, and will be created if it does not exist.

20427

The optional mode argument is the mode of the file, used

20428

only when the database has to be created. It defaults to octal

20429

0666 (and will be modified by the prevailing umask).

20430

Changed in version 2.2: The mode argument was ignored in earlier

20431

versions</description>

20432

<param name="filename" optional="0">filename</param><param name="flag" optional="1">flag</param><param name="mode" optional="1">mode</param>

20433

<insert>open(filename, [flag], [mode])</insert><dialog title="Insert open">open(%0, %1, %2)</dialog><info title="Info window"></info></function>

20434

20435

20436

<description>In addition to the methods provided by the UserDict.DictMixin class,

20437

dumbdbm objects provide the following methods.

20438

</description>

20439

20440

<description>Synchronize the on-disk directory and data files. This method is called by

20441

the sync method of Shelve objects.</description>

20442

20443

20444

20445

</group>

20446

</group>

20447

20448

<description>Low-level interface to compression and decompression

20449

routines compatible with gzip.

20450

For applications that require data compression, the functions in this

20451

module allow compression and decompression, using the zlib library.

20452

The zlib library has its own home page at

20453

http://www.gzip.org/zlib/. Version 1.1.3 is the

20454

most recent version as of September 2000; use a later version if one

20455

is available. There are known incompatibilities between the Python

20456

module and earlier versions of the zlib library.

20457

The available exception and functions in this module are:

20458

{error}

20459

Exception raised on compression and decompression errors.

20460

</description>

20461

20462

<description>Computes a Adler-32 checksum of string. (An Adler-32

20463

checksum is almost as reliable as a CRC32 but can be computed much

20464

more quickly.) If value is present, it is used as the

20465

starting value of the checksum; otherwise, a fixed default value is

20466

used. This allows computing a running checksum over the

20467

concatenation of several input strings. The algorithm is not

20468

cryptographically strong, and should not be used for

20469

authentication or digital signatures. Since the algorithm is

20470

designed for use as a checksum algorithm, it is not suitable for

20471

use as a general hash algorithm.</description>

20472

<param name="string" optional="0">string</param><param name="value" optional="1">value</param>

20473

<insert>adler32(string, [value])</insert><dialog title="Insert adler32">adler32(%0, %1)</dialog><info title="Info window"></info></function>

20474

20475

20476

<description>Compresses the data in string, returning a string contained

20477

compressed data. level is an integer from 1 to

20478

9 controlling the level of compression; 1 is fastest

20479

and produces the least compression, 9 is slowest and produces

20480

the most. The default value is 6. Raises the

20481

error exception if any error occurs.</description>

20482

<param name="string" optional="0">string</param><param name="level" optional="1">level</param>

20483

<insert>compress(string, [level])</insert><dialog title="Insert compress">compress(%0, %1)</dialog><info title="Info window"></info></function>

20484

20485

20486

<description>Returns a compression object, to be used for compressing data streams

20487

that won't fit into memory at once. level is an integer from

20488

1 to 9 controlling the level of compression; 1 is

20489

fastest and produces the least compression, 9 is slowest and

20490

produces the most. The default value is 6.</description>

20491

<param name="level" optional="0">level</param>

20492

<insert>compressobj(level)</insert><dialog title="Insert compressobj">compressobj(%0)</dialog><info title="Info window"></info></function>

20493

20494

20495

<description>Computes a CRC (Cyclic Redundancy Check)%

20496

</description>

20497

<param name="string" optional="0">string</param><param name="value" optional="1">value</param>

20498

<insert>crc32(string, [value])</insert><dialog title="Insert crc32">crc32(%0, %1)</dialog><info title="Info window"></info></function>

20499

20500

20501

<description>Decompresses the data in string, returning a string containing

20502

the uncompressed data. The wbits parameter controls the size of

20503

the window buffer. If bufsize is given, it is used as the

20504

initial size of the output buffer. Raises the error

20505

exception if any error occurs.

20506

The absolute value of wbits is the base two logarithm of the

20507

size of the history buffer (the ``window size'') used when compressing

20508

data. Its absolute value should be between 8 and 15 for the most

20509

recent versions of the zlib library, larger values resulting in better

20510

compression at the expense of greater memory usage. The default value

20511

is 15. When wbits is negative, the standard

20512

gzip header is suppressed; this is an undocumented feature

20513

of the zlib library, used for compatibility with unzip's

20514

compression file format.

20515

bufsize is the initial size of the buffer used to hold

20516

decompressed data. If more space is required, the buffer size will be

20517

increased as needed, so you don't have to get this value exactly

20518

right; tuning it will only save a few calls to malloc(). The

20519

default size is 16384.</description>

20520

<param name="string" optional="0">string</param><param name="wbits" optional="1">wbits</param><param name="bufsize" optional="1">bufsize</param>

20521

<insert>decompress(string, [wbits], [bufsize])</insert><dialog title="Insert decompress">decompress(%0, %1, %2)</dialog><info title="Info window"></info></function>

20522

20523

20524

<description>Returns a decompression object, to be used for decompressing data

20525

streams that won't fit into memory at once. The wbits

20526

parameter controls the size of the window buffer.</description>

20527

<param name="wbits" optional="0">wbits</param>

20528

<insert>decompressobj(wbits)</insert><dialog title="Insert decompressobj">decompressobj(%0)</dialog><info title="Info window"></info></function>

20529

20530

20531

<description>Compress string, returning a string containing compressed data

20532

for at least part of the data in string. This data should be

20533

concatenated to the output produced by any preceding calls to the

20534

compress() method. Some input may be kept in internal buffers

20535

for later processing.</description>

20536

<param name="stringstring" optional="0">stringstring</param>

20537

<insert>compress(stringstring)</insert><dialog title="Insert compress">compress(%0)</dialog><info title="Info window"></info></function>

20538

20539

20540

<description>All pending input is processed, and a string containing the remaining

20541

compressed output is returned. mode can be selected from the

20542

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

20543

are used to allow partial error recovery on decompression, while

20544

Z_FINISH finishes the compressed stream and prevents compressing any more data. After calling

20545

flush() with mode set to Z_FINISH, the

20546

compress() method cannot be called again; the only realistic

20547

action is to delete the object.</description>

20548

20549

<insert>flush(mode)</insert><dialog title="Insert flush">flush(%0)</dialog><info title="Info window"></info></function>

20550

20551

20552

<description>{max_length}

20553

Decompress string, returning a string containing the

20554

uncompressed data corresponding to at least part of the data in

20555

string. This data should be concatenated to the output produced

20556

by any preceding calls to the

20557

decompress() method. Some of the input data may be preserved

20558

in internal buffers for later processing.

20559

If the optional parameter max_length is supplied then the return value

20560

will be no longer than max_length. This may mean that not all of the

20561

compressed input can be processed; and unconsumed data will be stored

20562

in the attribute unconsumed_tail. This string must be passed

20563

to a subsequent call to decompress() if decompression is to

20564

continue. If max_length is not supplied then the whole input is

20565

decompressed, and unconsumed_tail is an empty string.</description>

20566

<param name="stringstring" optional="0">stringstring</param>

20567

<insert>decompress(stringstring)</insert><dialog title="Insert decompress">decompress(%0)</dialog><info title="Info window"></info></function>

20568

20569

20570

<description>All pending input is processed, and a string containing the remaining

20571

uncompressed output is returned. After calling flush(), the

20572

decompress() method cannot be called again; the only realistic

20573

action is to delete the object.</description>

20574

20575

<insert>flush()</insert><dialog title="Insert flush">flush()</dialog><info title="Info window"></info></function>

20576

20577

</group>

20578

20579

<description>Interfaces for gzip compression and

20580

decompression using file objects.

20581

The data compression provided by the zlib module is compatible

20582

with that used by the GNU compression program gzip.

20583

Accordingly, the gzip module provides the GzipFile

20584

class to read and write gzip-format files, automatically

20585

compressing or decompressing the data so it looks like an ordinary

20586

file object. Note that additional file formats which can be

20587

decompressed by the gzip and gunzip programs, such as those produced by compress and pack, are not

20588

supported by this module.

20589

The module defines the following items:

20590

</description>

20591

20592

<description>Constructor for the GzipFile class, which simulates most of

20593

the methods of a file object, with the exception of the readinto()

20594

and truncate() methods. At least one of

20595

fileobj and filename must be given a non-trivial value.

20596

The new class instance is based on fileobj, which can be a

20597

regular file, a StringIO object, or any other object which

20598

simulates a file. It defaults to None, in which case

20599

filename is opened to provide a file object.

20600

When fileobj is not None, the filename argument is

20601

only used to be included in the gzip file header, which may

20602

includes the original filename of the uncompressed file. It defaults

20603

to the filename of fileobj, if discernible; otherwise, it

20604

defaults to the empty string, and in this case the original filename

20605

is not included in the header.

20606

The mode argument can be any of 'r', 'rb',

20607

'a', 'ab', 'w', or 'wb', depending on

20608

whether the file will be read or written. The default is the mode of

20609

fileobj if discernible; otherwise, the default is 'rb'.

20610

If not given, the 'b' flag will be added to the mode to ensure the

20611

file is opened in binary mode for cross-platform portability.

20612

The compresslevel argument is an integer from 1 to

20613

9 controlling the level of compression; 1 is fastest and

20614

produces the least compression, and 9 is slowest and produces

20615

the most compression. The default is 9.

20616

Calling a GzipFile object's close() method does not

20617

close fileobj, since you might wish to append more material

20618

after the compressed data. This also allows you to pass a

20619

StringIO object opened for writing as fileobj, and

20620

retrieve the resulting memory buffer using the StringIO

20621

object's getvalue() method.</description>

20622

<param name="filename" optional="0">filename</param><param name="mode" optional="1">mode</param><param name="compresslevel" optional="1">compresslevel</param><param name="fileobj" optional="1">fileobj</param>

20623

<insert>GzipFile(filename, [mode], [compresslevel], [fileobj])</insert><dialog title="Insert GzipFile">GzipFile(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

20624

20625

20626

<description>This is a shorthand for GzipFile(filename,

20627

mode, compresslevel). The filename

20628

argument is required; mode defaults to 'rb' and

20629

compresslevel defaults to 9.</description>

20630

<param name="filename" optional="0">filename</param><param name="mode" optional="1">mode</param><param name="compresslevel" optional="1">compresslevel</param>

20631

<insert>open(filename, [mode], [compresslevel])</insert><dialog title="Insert open">open(%0, %1, %2)</dialog><info title="Info window"></info></function>

20632

20633

</group>

20634

20635

<description>Interface to compression and decompression

20636

routines compatible with bzip2.

20637

New in version 2.3

20638

This module provides a comprehensive interface for the bz2 compression library.

20639

It implements a complete file interface, one-shot (de)compression functions,

20640

and types for sequential (de)compression.

20641

Here is a resume of the features offered by the bz2 module:

20642

BZ2File class implements a complete file interface, including

20643

readline(), readlines(),

20644

writelines(), seek(), etc;

20645

BZ2File class implements emulated seek() support;

20646

BZ2File class implements universal newline support;

20647

BZ2File class offers an optimized line iteration using

20648

the readahead algorithm borrowed from file objects;

20649

Sequential (de)compression supported by BZ2Compressor and

20650

BZ2Decompressor classes;

20651

One-shot (de)compression supported by compress() and

20652

decompress() functions;

20653

Thread safety uses individual locking mechanism;

20654

Complete inline documentation;

20655

</description>

20656

20657

<description>Handling of compressed files is offered by the BZ2File class.

20658

</description>

20659

20660

<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

20661

it doesn't exist, and truncated otherwise. If buffering is given,

20662

0 means unbuffered, and larger numbers specify the buffer size;

20663

the default is 0. If

20664

compresslevel is given, it must be a number between 1 and

20665

9; the default is 9.

20666

Add a U to mode to open the file for input with universal newline

20667

support. Any line ending in the input file will be seen as a

20668

\n in Python. Also, a file so opened gains the

20669

attribute newlines; the value for this attribute is one of

20670

None (no newline read yet), '\r', '\n',

20671

'\r\n' or a tuple containing all the newline types

20672

seen. Universal newlines are available only when reading.

20673

Instances support iteration in the same way as normal file

20674

instances.</description>

20675

<param name="filename" optional="0">filename</param><param name="mode" optional="1">mode</param><param name="buffering" optional="1">buffering</param><param name="compresslevel" optional="1">compresslevel</param>

20676

<insert>BZ2File(filename, [mode], [buffering], [compresslevel])</insert><dialog title="Insert BZ2File">BZ2File(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

20677

20678

</group>

20679

20680

<description>Sequential compression and decompression is done using the classes

20681

BZ2Compressor and BZ2Decompressor.

20682

</description>

20683

20684

<description>Create a new compressor object. This object may be used to compress

20685

data sequentially. If you want to compress data in one shot, use the

20686

compress() function instead. The compresslevel parameter,

20687

if given, must be a number between 1 and 9; the default

20688

is 9.</description>

20689

<param name="compresslevel" optional="0">compresslevel</param>

20690

<insert>BZ2Compressor(compresslevel)</insert><dialog title="Insert BZ2Compressor">BZ2Compressor(%0)</dialog><info title="Info window"></info></function>

20691

20692

20693

<description>Create a new decompressor object. This object may be used to decompress

20694

data sequentially. If you want to decompress data in one shot, use the

20695

decompress() function instead.</description>

20696

20697

<insert>BZ2Decompressor()</insert><dialog title="Insert BZ2Decompressor">BZ2Decompressor()</dialog><info title="Info window"></info></function>

20698

20699

</group>

20700

20701

<description>One-shot compression and decompression is provided through the

20702

compress() and decompress() functions.

20703

</description>

20704

20705

<description>Compress data in one shot. If you want to compress data sequentially,

20706

use an instance of BZ2Compressor instead. The compresslevel

20707

parameter, if given, must be a number between 1 and 9;

20708

the default is 9.</description>

20709

<param name="data" optional="0">data</param><param name="compresslevel" optional="1">compresslevel</param>

20710

<insert>compress(data, [compresslevel])</insert><dialog title="Insert compress">compress(%0, %1)</dialog><info title="Info window"></info></function>

20711

20712

20713

<description>Decompress data in one shot. If you want to decompress data

20714

sequentially, use an instance of BZ2Decompressor instead.</description>

20715

<param name="datadata" optional="0">datadata</param>

20716

<insert>decompress(datadata)</insert><dialog title="Insert decompress">decompress(%0)</dialog><info title="Info window"></info></function>

20717

20718

</group>

20719

</group>

20720

20721

<description>Read and write ZIP-format archive files.

20722

% LaTeX markup by Fred L. Drake, Jr. <fdrake@acm.org>

20723

New in version 1.6

20724

The ZIP file format is a common archive and compression standard.

20725

This module provides tools to create, read, write, append, and list a

20726

ZIP file. Any advanced use of this module will require an

20727

understanding of the format, as defined in

20728

PKZIP Application

20729

Note.

20730

This module does not currently handle ZIP files which have appended

20731

comments, or multi-disk ZIP files.

20732

The available attributes of this module are:

20733

{error}

20734

The error raised for bad ZIP files.

20735

{ZipFile}

20736

The class for reading and writing ZIP files. See

20737

``ZipFile Objects'' (section zipfile-objects) for

20738

constructor details.

20739

{PyZipFile}

20740

Class for creating ZIP archives containing Python libraries.

20741

</description>

20742

20743

<description>Class used the represent infomation about a member of an archive.

20744

Instances of this class are returned by the getinfo() and

20745

infolist() methods of ZipFile objects. Most users

20746

of the zipfile module will not need to create these, but

20747

only use those created by this module.

20748

filename should be the full name of the archive member, and

20749

date_time should be a tuple containing six fields which

20750

describe the time of the last modification to the file; the fields

20751

are described in section zipinfo-objects, ``ZipInfo Objects.''</description>

20752

<param name="filename" optional="0">filename</param><param name="date_time" optional="1">date_time</param>

20753

<insert>ZipInfo(filename, [date_time])</insert><dialog title="Insert ZipInfo">ZipInfo(%0, %1)</dialog><info title="Info window"></info></function>

20754

20755

20756

<description>Returns True if filename is a valid ZIP file based on its magic

20757

number, otherwise returns False. This module does not currently

20758

handle ZIP files which have appended comments.</description>

20759

<param name="filenamefilename" optional="0">filenamefilename</param>

20760

<insert>is_zipfile(filenamefilename)</insert><dialog title="Insert is_zipfile">is_zipfile(%0)</dialog><info title="Info window"></info></function>

20761

20762

20763

20764

<description>Open a ZIP file, where file can be either a path to a file

20765

(a string) or a file-like object. The mode parameter

20766

should be 'r' to read an existing file, 'w' to

20767

truncate and write a new file, or 'a' to append to an

20768

existing file. For mode is 'a' and file

20769

refers to an existing ZIP file, then additional files are added to

20770

it. If file does not refer to a ZIP file, then a new ZIP

20771

archive is appended to the file. This is meant for adding a ZIP

20772

archive to another file, such as python.exe. Using

20773

cat myzip.zip >> python.exe

20774

also works, and at least WinZip can read such files.

20775

compression is the ZIP compression method to use when writing

20776

the archive, and should be ZIP_STORED or

20777

ZIP_DEFLATED; unrecognized values will cause

20778

RuntimeError to be raised. If ZIP_DEFLATED

20779

is specified but the zlib module is not available,

20780

RuntimeError is also raised. The default is

20781

ZIP_STORED.</description>

20782

<param name="file" optional="0">file</param><param name="mode" optional="1">mode</param><param name="compression" optional="1">compression</param>

20783

<insert>ZipFile(file, [mode], [compression])</insert><dialog title="Insert ZipFile">ZipFile(%0, %1, %2)</dialog><info title="Info window"></info></function>

20784

20785

20786

<description>Close the archive file. You must call close() before

20787

exiting your program or essential records will not be written.</description>

20788

20789

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

20790

20791

20792

<description>Return a ZipInfo object with information about the archive

20793

member name.</description>

20794

<param name="namename" optional="0">namename</param>

20795

<insert>getinfo(namename)</insert><dialog title="Insert getinfo">getinfo(%0)</dialog><info title="Info window"></info></function>

20796

20797

20798

<description>Return a list containing a ZipInfo object for each member of

20799

the archive. The objects are in the same order as their entries in

20800

the actual ZIP file on disk if an existing archive was opened.</description>

20801

20802

<insert>infolist()</insert><dialog title="Insert infolist">infolist()</dialog><info title="Info window"></info></function>

20803

20804

20805

<description>Return a list of archive members by name.</description>

20806

20807

<insert>namelist()</insert><dialog title="Insert namelist">namelist()</dialog><info title="Info window"></info></function>

20808

20809

20810

<description>Print a table of contents for the archive to sys.stdout.</description>

20811

20812

<insert>printdir()</insert><dialog title="Insert printdir">printdir()</dialog><info title="Info window"></info></function>

20813

20814

20815

<description>Return the bytes of the file in the archive. The archive must be

20816

open for read or append.</description>

20817

<param name="namename" optional="0">namename</param>

20818

<insert>read(namename)</insert><dialog title="Insert read">read(%0)</dialog><info title="Info window"></info></function>

20819

20820

20821

<description>Read all the files in the archive and check their CRC's. Return the

20822

name of the first bad file, or else return None.</description>

20823

20824

<insert>testzip()</insert><dialog title="Insert testzip">testzip()</dialog><info title="Info window"></info></function>

20825

20826

20827

<description>Write the file named filename to the archive, giving it the

20828

archive name arcname (by default, this will be the same as

20829

filename). If given, compress_type overrides the value

20830

given for the compression parameter to the constructor for

20831

the new entry. The archive must be open with mode 'w' or

20832

'a'.</description>

20833

<param name="filename" optional="0">filename</param><param name="arcname" optional="1">arcname</param><param name="compress_type" optional="1">compress_type</param>

20834

<insert>write(filename, [arcname], [compress_type])</insert><dialog title="Insert write">write(%0, %1, %2)</dialog><info title="Info window"></info></function>

20835

20836

20837

<description>Write the string bytes to the archive; zinfo_or_arcname

20838

is either the file name it will be given in the archive, or a

20839

ZipInfo instance. If it's an instance, at least the

20840

filename, date, and time must be given. If it's a name, the date

20841

and time is set to the current date and time. The archive must be

20842

opened with mode 'w' or 'a'.</description>

20843

<param name="zinfo_or_arcname" optional="0">zinfo_or_arcname</param><param name="bytes bytes" optional="0">bytes bytes</param>

20844

<insert>writestr(zinfo_or_arcname, bytes bytes)</insert><dialog title="Insert writestr">writestr(%0, %1)</dialog><info title="Info window"></info></function>

20845

20846

</group>

20847

20848

<description>The PyZipFile constructor takes the same parameters as the

20849

ZipFile constructor. Instances have one method in addition to

20850

those of ZipFile objects.

20851

</description>

20852

20853

<description>Search for files *.py and add the corresponding file to the

20854

archive. The corresponding file is a *.pyo file if

20855

available, else a *.pyc file, compiling if necessary. If the

20856

pathname is a file, the filename must end with .py, and just

20857

the (corresponding *.py[co]) file is added at the top level

20858

(no path information). If it is a directory, and the directory is

20859

not a package directory, then all the files *.py[co] are

20860

added at the top level. If the directory is a package directory,

20861

then all *.py[oc] are added under the package name as a file

20862

path, and if any subdirectories are package directories, all of

20863

these are added recursively. basename is intended for

20864

internal use only. The writepy() method makes archives

20865

with file names like this:

20866

string.pyc # Top level name test/__init__.pyc # Package directory test/testall.pyc # Module test.testall

20867

test/bogus/__init__.pyc # Subpackage directory test/bogus/myfile.pyc # Submodule test.bogus.myfile

20868

</description>

20869

<param name="pathname" optional="0">pathname</param><param name="basename" optional="1">basename</param>

20870

<insert>writepy(pathname, [basename])</insert><dialog title="Insert writepy">writepy(%0, %1)</dialog><info title="Info window"></info></function>

20871

20872

</group>

20873

20874

</group>

20875

</group>

20876

20877

<description>Read and write tar-format archive files.

20878

New in version 2.3

20879

The tarfile module makes it possible to read and create tar archives.

20880

Some facts and figures:

20881

reads and writes gzip and bzip2 compressed archives.

20882

creates POSIX 1003.1-1990 compliant or GNU tar compatible archives.

20883

reads GNU tar extensions longname, longlink and

20884

sparse.

20885

stores pathnames of unlimited length using GNU tar extensions.

20886

handles directories, regular files, hardlinks, symbolic links, fifos,

20887

character devices and block devices and is able to acquire and

20888

restore file information like timestamp, access permissions and owner.

20889

can handle tape devices.

20890

</description>

20891

20892

<description>Return a TarFile object for the pathname name.

20893

For detailed information on TarFile objects,

20894

see TarFile Objects (section tarfile-objects).

20895

mode has to be a string of the form 'filemode[:compression]',

20896

it defaults to 'r'. Here is a full list of mode combinations:

20897

{c|l}{code}{mode}{action}

20898

'r'{Open for reading with transparent compression (recommended).}

20899

'r:'{Open for reading exclusively without compression.}

20900

'r:gz'{Open for reading with gzip compression.}

20901

'r:bz2'{Open for reading with bzip2 compression.}

20902

'a' or 'a:'{Open for appending with no compression.}

20903

'w' or 'w:'{Open for uncompressed writing.}

20904

'w:gz'{Open for gzip compressed writing.}

20905

'w:bz2'{Open for bzip2 compressed writing.}

20906

Note that 'a:gz' or 'a:bz2' is not possible.

20907

If mode is not suitable to open a certain (compressed) file for

20908

reading, ReadError is raised. Use mode 'r' to

20909

avoid this. If a compression method is not supported,

20910

CompressionError is raised.

20911

If fileobj is specified, it is used as an alternative to

20912

a file object opened for name.

20913

For special purposes, there is a second format for mode:

20914

'filemode|[compression]'. open will return a TarFile

20915

object that processes its data as a stream of blocks. No random

20916

seeking will be done on the file. If given, fileobj may be any

20917

object that has a read() resp. write() method.

20918

bufsize specifies the blocksize and defaults to 20 * 512

20919

bytes. Use this variant in combination with e.g. sys.stdin, a socket

20920

file object or a tape device.

20921

However, such a TarFile object is limited in that it does not allow

20922

to be accessed randomly, see Examples (section

20923

tar-examples).

20924

The currently possible modes:

20925

{c|l}{code}{mode}{action}

20926

'r|'{Open a stream of uncompressed tar blocks for reading.}

20927

'r|gz'{Open a gzip compressed stream for reading.}

20928

'r|bz2'{Open a bzip2 compressed stream for reading.}

20929

'w|'{Open an uncompressed stream for writing.}

20930

'w|gz'{Open an gzip compressed stream for writing.}

20931

'w|bz2'{Open an bzip2 compressed stream for writing.}

20932

</description>

20933

<param name="name" optional="0">name</param><param name="mode" optional="1">mode</param><param name="fileobj" optional="1">fileobj</param><param name="bufsize" optional="1">bufsize</param>

20934

<insert>open(name, [mode], [fileobj], [bufsize])</insert><dialog title="Insert open">open(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

20935

20936

20937

<description>Return True if name is a tar archive file, that the

20938

tarfile module can read.</description>

20939

<param name="namename" optional="0">namename</param>

20940

<insert>is_tarfile(namename)</insert><dialog title="Insert is_tarfile">is_tarfile(%0)</dialog><info title="Info window"></info></function>

20941

20942

20943

<description>Class for limited access to tar archives with a zipfile-like

20944

interface. Please consult the documentation of zipfile for more

20945

details.

20946

compression must be one of the following constants:

20947

{TAR_PLAIN}

20948

Constant for an uncompressed tar archive.

20949

{TAR_GZIPPED}

20950

Constant for a gzip compressed tar archive.

20951

</description>

20952

<param name="filename" optional="0">filename</param><param name="mode" optional="1">mode</param><param name="compression" optional="1">compression</param>

20953

<insert>TarFileCompat(filename, [mode], [compression])</insert><dialog title="Insert TarFileCompat">TarFileCompat(%0, %1, %2)</dialog><info title="Info window"></info></function>

20954

20955

20956

<description>The TarFile object provides an interface to a tar archive. A tar

20957

archive is a sequence of blocks. An archive member (a stored file) is made up

20958

of a header block followed by data blocks. It is possible, to store a file in a

20959

tar archive several times. Each archive member is represented by a

20960

TarInfo object, see TarInfo Objects (section

20961

tarinfo-objects) for details.

20962

</description>

20963

20964

<description>Open an (uncompressed) tar archive name.

20965

mode is either 'r' to read from an existing archive,

20966

'a' to append data to an existing file or 'w' to create a new

20967

file overwriting an existing one. mode defaults to 'r'.

20968

If fileobj is given, it is used for reading or writing data.

20969

If it can be determined, mode is overridden by fileobj's mode.

20970

fileobj is not closed, when TarFile is closed.

20971

</description>

20972

<param name="name" optional="0">name</param><param name="mode" optional="1">mode</param><param name="fileobj" optional="1">fileobj</param>

20973

<insert>TarFile(name, [mode], [fileobj])</insert><dialog title="Insert TarFile">TarFile(%0, %1, %2)</dialog><info title="Info window"></info></function>

20974

20975

20976

<description>Alternative constructor. The open() function on module level is

20977

actually a shortcut to this classmethod. See section module-tarfile

20978

for details.</description>

20979

20980

20981

20982

20983

<description>Return a TarInfo object for member name. If name can

20984

not be found in the archive, KeyError is raised.

20985

If a member occurs more than once in the archive, its last

20986

occurence is assumed to be the most up-to-date version.

20987

</description>

20988

<param name="namename" optional="0">namename</param>

20989

<insert>getmember(namename)</insert><dialog title="Insert getmember">getmember(%0)</dialog><info title="Info window"></info></function>

20990

20991

20992

<description>Return the members of the archive as a list of TarInfo objects.

20993

The list has the same order as the members in the archive.</description>

20994

20995

<insert>getmembers()</insert><dialog title="Insert getmembers">getmembers()</dialog><info title="Info window"></info></function>

20996

20997

20998

<description>Return the members as a list of their names. It has the same order as

20999

the list returned by getmembers().</description>

21000

21001

<insert>getnames()</insert><dialog title="Insert getnames">getnames()</dialog><info title="Info window"></info></function>

21002

21003

21004

<description>Print a table of contents to sys.stdout. If verbose is

21005

False, only the names of the members are printed. If it is

21006

True, an "ls -l"-like output is produced.</description>

21007

<param name="verbose" optional="0" default="Trueverbose=True">verbose</param>

21008

<insert>list(verbose)</insert><dialog title="Insert list">list(%0)</dialog><info title="Info window"></info></function>

21009

21010

21011

<description>Return the next member of the archive as a TarInfo object, when

21012

TarFile is opened for reading. Return None if there is no

21013

more available.</description>

21014

21015

21016

21017

21018

<description>Extract a member from the archive to the current working directory,

21019

using its full name. Its file information is extracted as accurately as

21020

possible.

21021

member may be a filename or a TarInfo object.

21022

You can specify a different directory using path.</description>

21023

<param name="member" optional="0">member</param><param name="path" optional="1">path</param>

21024

<insert>extract(member, [path])</insert><dialog title="Insert extract">extract(%0, %1)</dialog><info title="Info window"></info></function>

21025

21026

21027

<description>Extract a member from the archive as a file object.

21028

member may be a filename or a TarInfo object.

21029

If member is a regular file, a file-like object is returned.

21030

If member is a link, a file-like object is constructed from the

21031

link's target.

21032

If member is none of the above, None is returned.

21033

The file-like object is read-only and provides the following methods:

21034

read(), readline(), readlines(),

21035

seek(), tell().

21036

</description>

21037

<param name="membermember" optional="0">membermember</param>

21038

<insert>extractfile(membermember)</insert><dialog title="Insert extractfile">extractfile(%0)</dialog><info title="Info window"></info></function>

21039

21040

21041

<description>Add the file name to the archive. name may be any type

21042

of file (directory, fifo, symbolic link, etc.).

21043

If given, arcname specifies an alternative name for the file in the

21044

archive. Directories are added recursively by default.

21045

This can be avoided by setting recursive to False.</description>

21046

<param name="name" optional="0">name</param><param name="arcname" optional="1">arcname</param><param name="recursive" optional="1" default="True">recursive</param>

21047

<insert>add(name, [arcname], [recursive=True])</insert><dialog title="Insert add">add(%0, %1, %2)</dialog><info title="Info window"></info></function>

21048

21049

21050

<description>Add the TarInfo object tarinfo to the archive.

21051

If fileobj is given, tarinfo.size bytes are read

21052

from it and added to the archive. You can create TarInfo objects

21053

using gettarinfo().

21054

On Windows platforms, fileobj should always be opened with mode

21055

'rb' to avoid irritation about the file size.

21056

</description>

21057

<param name="tarinfo" optional="0">tarinfo</param><param name="fileobj" optional="1">fileobj</param>

21058

<insert>addfile(tarinfo, [fileobj])</insert><dialog title="Insert addfile">addfile(%0, %1)</dialog><info title="Info window"></info></function>

21059

21060

21061

<description>Create a TarInfo object for either the file name or the

21062

file object fileobj (using os.fstat() on its file descriptor).

21063

You can modify some of the TarInfo's attributes before you add it

21064

using addfile().

21065

If given, arcname specifies an alternative name for the file in the

21066

archive.</description>

21067

<param name="name" optional="0">name</param><param name="arcname" optional="1">arcname</param><param name="fileobj" optional="1">fileobj</param>

21068

<insert>gettarinfo(name, [arcname], [fileobj])</insert><dialog title="Insert gettarinfo">gettarinfo(%0, %1, %2)</dialog><info title="Info window"></info></function>

21069

21070

21071

<description>Close the TarFile. In write-mode, two finishing zero blocks are

21072

appended to the archive.</description>

21073

21074

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

21075

21076

</group>

21077

21078

<description>A TarInfo object represents one member in a TarFile. Aside from

21079

storing all required attributes of a file (like file type, size, time,

21080

permissions, owner etc.), it provides some useful methods to determine its

21081

type. It does not contain the file's data itself.

21082

TarInfo objects are returned by TarFile's methods

21083

getmember(), getmembers() and gettarinfo().

21084

</description>

21085

21086

<description>Create a TarInfo object.</description>

21087

21088

<insert>TarInfo(name)</insert><dialog title="Insert TarInfo">TarInfo(%0)</dialog><info title="Info window"></info></function>

21089

21090

21091

<description>Create and return a TarInfo object from a string buffer.</description>

21092

21093

<insert>frombuf()</insert><dialog title="Insert frombuf">frombuf()</dialog><info title="Info window"></info></function>

21094

21095

21096

<description>Create a string buffer from a TarInfo object.</description>

21097

21098

<insert>tobuf()</insert><dialog title="Insert tobuf">tobuf()</dialog><info title="Info window"></info></function>

21099

21100

21101

<description>Return True if the Tarinfo object is a regular file.</description>

21102

21103

<insert>isfile()</insert><dialog title="Insert isfile">isfile()</dialog><info title="Info window"></info></function>

21104

21105

21106

<description>Same as isfile().</description>

21107

21108

<insert>isreg()</insert><dialog title="Insert isreg">isreg()</dialog><info title="Info window"></info></function>

21109

21110

21111

<description>Return True if it is a directory.</description>

21112

21113

<insert>isdir()</insert><dialog title="Insert isdir">isdir()</dialog><info title="Info window"></info></function>

21114

21115

21116

<description>Return True if it is a symbolic link.</description>

21117

21118

<insert>issym()</insert><dialog title="Insert issym">issym()</dialog><info title="Info window"></info></function>

21119

21120

21121

<description>Return True if it is a hard link.</description>

21122

21123

<insert>islnk()</insert><dialog title="Insert islnk">islnk()</dialog><info title="Info window"></info></function>

21124

21125

21126

<description>Return True if it is a character device.</description>

21127

21128

<insert>ischr()</insert><dialog title="Insert ischr">ischr()</dialog><info title="Info window"></info></function>

21129

21130

21131

<description>Return True if it is a block device.</description>

21132

21133

<insert>isblk()</insert><dialog title="Insert isblk">isblk()</dialog><info title="Info window"></info></function>

21134

21135

21136

<description>Return True if it is a FIFO.</description>

21137

21138

<insert>isfifo()</insert><dialog title="Insert isfifo">isfifo()</dialog><info title="Info window"></info></function>

21139

21140

21141

<description>Return True if it is one of character device, block device or FIFO.</description>

21142

21143

<insert>isdev()</insert><dialog title="Insert isdev">isdev()</dialog><info title="Info window"></info></function>

21144

21145

</group>

21146

21147

</group>

21148

</group>

21149

21150

<description>Unix

21151

GNU readline support for Python.

21152

The readline module defines a number of functions used either

21153

directly or from the rlcompleter module to facilitate

21154

completion and history file read and write from the Python

21155

interpreter.

21156

The readline module defines the following functions:

21157

</description>

21158

21159

<description>Parse and execute single line of a readline init file.</description>

21160

<param name="stringstring" optional="0">stringstring</param>

21161

<insert>parse_and_bind(stringstring)</insert><dialog title="Insert parse_and_bind">parse_and_bind(%0)</dialog><info title="Info window"></info></function>

21162

21163

21164

<description>Return the current contents of the line buffer.</description>

21165

21166

<insert>get_line_buffer()</insert><dialog title="Insert get_line_buffer">get_line_buffer()</dialog><info title="Info window"></info></function>

21167

21168

21169

<description>Insert text into the command line.</description>

21170

<param name="stringstring" optional="0">stringstring</param>

21171

<insert>insert_text(stringstring)</insert><dialog title="Insert insert_text">insert_text(%0)</dialog><info title="Info window"></info></function>

21172

21173

21174

<description>Parse a readline initialization file.

21175

The default filename is the last filename used.</description>

21176

<param name="filename" optional="0">filename</param>

21177

<insert>read_init_file(filename)</insert><dialog title="Insert read_init_file">read_init_file(%0)</dialog><info title="Info window"></info></function>

21178

21179

21180

<description>Load a readline history file.

21181

The default filename is .</description>

21182

<param name="filename" optional="0">filename</param>

21183

<insert>read_history_file(filename)</insert><dialog title="Insert read_history_file">read_history_file(%0)</dialog><info title="Info window"></info></function>

21184

21185

21186

<description>Save a readline history file.

21187

The default filename is .</description>

21188

<param name="filename" optional="0">filename</param>

21189

<insert>write_history_file(filename)</insert><dialog title="Insert write_history_file">write_history_file(%0)</dialog><info title="Info window"></info></function>

21190

21191

21192

<description>Clear the current history. (Note: this function is not available if

21193

the installed version of GNU readline doesn't support it.)

21194

New in version 2.4</description>

21195

21196

<insert>clear_history()</insert><dialog title="Insert clear_history">clear_history()</dialog><info title="Info window"></info></function>

21197

21198

21199

<description>Return the desired length of the history file. Negative values imply

21200

unlimited history file size.</description>

21201

21202

<insert>get_history_length()</insert><dialog title="Insert get_history_length">get_history_length()</dialog><info title="Info window"></info></function>

21203

21204

21205

<description>Set the number of lines to save in the history file.

21206

write_history_file() uses this value to truncate the

21207

history file when saving. Negative values imply unlimited history

21208

file size.</description>

21209

<param name="lengthlength" optional="0">lengthlength</param>

21210

<insert>set_history_length(lengthlength)</insert><dialog title="Insert set_history_length">set_history_length(%0)</dialog><info title="Info window"></info></function>

21211

21212

21213

<description>Set or remove the startup_hook function. If function is specified,

21214

it will be used as the new startup_hook function; if omitted or

21215

None, any hook function already installed is removed. The

21216

startup_hook function is called with no arguments just

21217

before readline prints the first prompt.</description>

21218

<param name="function" optional="0">function</param>

21219

<insert>set_startup_hook(function)</insert><dialog title="Insert set_startup_hook">set_startup_hook(%0)</dialog><info title="Info window"></info></function>

21220

21221

21222

<description>Set or remove the pre_input_hook function. If function is specified,

21223

it will be used as the new pre_input_hook function; if omitted or

21224

None, any hook function already installed is removed. The

21225

pre_input_hook function is called with no arguments after the first prompt

21226

has been printed and just before readline starts reading input characters.</description>

21227

<param name="function" optional="0">function</param>

21228

<insert>set_pre_input_hook(function)</insert><dialog title="Insert set_pre_input_hook">set_pre_input_hook(%0)</dialog><info title="Info window"></info></function>

21229

21230

21231

<description>Set or remove the completer function. If function is specified,

21232

it will be used as the new completer function; if omitted or

21233

None, any completer function already installed is removed. The

21234

completer function is called as function(text,

21235

state), for state in 0, 1, 2, ...,

21236

until it returns a non-string value. It should return the next

21237

possible completion starting with text.</description>

21238

<param name="function" optional="0">function</param>

21239

<insert>set_completer(function)</insert><dialog title="Insert set_completer">set_completer(%0)</dialog><info title="Info window"></info></function>

21240

21241

21242

<description>Get the completer function, or None if no completer function

21243

has been set. New in version 2.3</description>

21244

21245

<insert>get_completer()</insert><dialog title="Insert get_completer">get_completer()</dialog><info title="Info window"></info></function>

21246

21247

21248

<description>Get the beginning index of the readline tab-completion scope.</description>

21249

21250

<insert>get_begidx()</insert><dialog title="Insert get_begidx">get_begidx()</dialog><info title="Info window"></info></function>

21251

21252

21253

<description>Get the ending index of the readline tab-completion scope.</description>

21254

21255

<insert>get_endidx()</insert><dialog title="Insert get_endidx">get_endidx()</dialog><info title="Info window"></info></function>

21256

21257

21258

<description>Set the readline word delimiters for tab-completion.</description>

21259

<param name="stringstring" optional="0">stringstring</param>

21260

<insert>set_completer_delims(stringstring)</insert><dialog title="Insert set_completer_delims">set_completer_delims(%0)</dialog><info title="Info window"></info></function>

21261

21262

21263

<description>Get the readline word delimiters for tab-completion.</description>

21264

21265

<insert>get_completer_delims()</insert><dialog title="Insert get_completer_delims">get_completer_delims()</dialog><info title="Info window"></info></function>

21266

21267

21268

<description>Append a line to the history buffer, as if it was the last line typed.</description>

21269

<param name="lineline" optional="0">lineline</param>

21270

<insert>add_history(lineline)</insert><dialog title="Insert add_history">add_history(%0)</dialog><info title="Info window"></info></function>

21271

21272

21273

</group>

21274

</group>

21275

21276

<description>Unix

21277

Python identifier completion for the GNU readline library.

21278

The rlcompleter module defines a completion function for

21279

the readline module by completing valid Python identifiers

21280

and keywords.

21281

This module is -specific due to its dependence on the

21282

readline module.

21283

The rlcompleter module defines the Completer class.

21284

Example:

21285

>>> import rlcompleter

21286

>>> import readline

21287

>>> readline.parse_and_bind("tab: complete")

21288

>>> readline. <TAB PRESSED>

21289

readline.__doc__ readline.get_line_buffer readline.read_init_file

21290

readline.__file__ readline.insert_text readline.set_completer

21291

readline.__name__ readline.parse_and_bind

21292

>>> readline.

21293

The rlcompleter module is designed for use with Python's

21294

interactive mode. A user can add the following lines to his or her

21295

initialization file (identified by the PYTHONSTARTUP

21296

environment variable) to get automatic Tab completion:

21297

try:

21298

import readline

21299

except ImportError:

21300

print "Module readline not available."

21301

else:

21302

import rlcompleter

21303

readline.parse_and_bind("tab: complete")

21304

</description>

21305

21306

<description>Completer objects have the following method:

21307

</description>

21308

21309

<description>Return the stateth completion for text.

21310

If called for text that doesn't include a period character

21311

(.), it will complete from names currently defined in

21312

__main__, __builtin__ and

21313

keywords (as defined by the keyword module).

21314

If called for a dotted name, it will try to evaluate anything without

21315

obvious side-effects (functions will not be evaluated, but it

21316

can generate calls to __getattr__()) up to the last part, and

21317

find matches for the rest via the dir() function.</description>

21318

<param name="text" optional="0">text</param><param name="state state" optional="0">state state</param>

21319

<insert>complete(text, state state)</insert><dialog title="Insert complete">complete(%0, %1)</dialog><info title="Info window"></info></function>

21320

21321

</group>

21322

</group>

21323

</group>

21324

21325

21326

<description>Unix

21327

The most common calls (normally used

21328

via module os).

21329

This module provides access to operating system functionality that is

21330

standardized by the C Standard and the standard (a thinly

21331

disguised interface).

21332

Do not import this module directly. Instead, import the

21333

module os, which provides a portable version of this

21334

interface. On , the os module provides a superset of

21335

the posix interface. On non- operating systems the

21336

posix module is not available, but a subset is always

21337

available through the os interface. Once os is

21338

imported, there is no performance penalty in using it instead

21339

of posix. In addition, osos

21340

provides some additional functionality, such as automatically calling

21341

putenv() when an entry in os.environ is changed.

21342

The descriptions below are very terse; refer to the corresponding

21343

manual (or documentation) entry for more information.

21344

Arguments called path refer to a pathname given as a string.

21345

Errors are reported as exceptions; the usual exceptions are given for

21346

type errors, while errors reported by the system calls raise

21347

error (a synonym for the standard exception

21348

OSError), described below.

21349

</description>

21350

21351

</group>

21352

21353

</group>

21354

</group>

21355

21356

<description>Unix

21357

The password database (getpwnam() and friends).

21358

This module provides access to the user account and password

21359

database. It is available on all versions.

21360

Password database entries are reported as a tuple-like object, whose

21361

attributes correspond to the members of the passwd structure

21362

(Attribute field below, see <pwd.h>):

21363

{r|l|l}{textrm}{Index}{Attribute}{Meaning}

21364

0{pw_name}{Login name}

21365

1{pw_passwd}{Optional encrypted password}

21366

2{pw_uid}{Numerical user ID}

21367

3{pw_gid}{Numerical group ID}

21368

4{pw_gecos}{User name or comment field}

21369

5{pw_dir}{User home directory}

21370

6{pw_shell}{User command interpreter}

21371

The uid and gid items are integers, all others are strings.

21372

KeyError is raised if the entry asked for cannot be found.

21373

In traditional the field pw_passwd usually

21374

contains a password encrypted with a DES derived algorithm (see module

21375

cryptcrypt). However most modern unices use a so-called shadow password system. On those unices the

21376

field pw_passwd only contains a asterisk ('*') or the letter x where the encrypted password is stored in a file

21377

/etc/shadow which is not world readable.

21378

It defines the following items:

21379

</description>

21380

21381

<description>Return the password database entry for the given numeric user ID.</description>

21382

<param name="uiduid" optional="0">uiduid</param>

21383

<insert>getpwuid(uiduid)</insert><dialog title="Insert getpwuid">getpwuid(%0)</dialog><info title="Info window"></info></function>

21384

21385

21386

<description>Return the password database entry for the given user name.</description>

21387

<param name="namename" optional="0">namename</param>

21388

<insert>getpwnam(namename)</insert><dialog title="Insert getpwnam">getpwnam(%0)</dialog><info title="Info window"></info></function>

21389

21390

21391

<description>Return a list of all available password database entries, in arbitrary order.</description>

21392

21393

<insert>getpwall()</insert><dialog title="Insert getpwall">getpwall()</dialog><info title="Info window"></info></function>

21394

21395

</group>

21396

21397

<description>Unix

21398

The group database (getgrnam() and friends).

21399

This module provides access to the group database.

21400

It is available on all versions.

21401

Group database entries are reported as a tuple-like object, whose

21402

attributes correspond to the members of the group structure

21403

(Attribute field below, see <pwd.h>):

21404

{r|l|l}{textrm}{Index}{Attribute}{Meaning}

21405

0{gr_name}{the name of the group}

21406

1{gr_passwd}{the (encrypted) group password; often empty}

21407

2{gr_gid}{the numerical group ID}

21408

3{gr_mem}{all the group member's user names}

21409

The gid is an integer, name and password are strings, and the member

21410

list is a list of strings.

21411

(Note that most users are not explicitly listed as members of the

21412

group they are in according to the password database. Check both

21413

databases to get complete membership information.)

21414

It defines the following items:

21415

</description>

21416

21417

<description>Return the group database entry for the given numeric group ID.

21418

KeyError is raised if the entry asked for cannot be found.</description>

21419

<param name="gidgid" optional="0">gidgid</param>

21420

<insert>getgrgid(gidgid)</insert><dialog title="Insert getgrgid">getgrgid(%0)</dialog><info title="Info window"></info></function>

21421

21422

21423

<description>Return the group database entry for the given group name.

21424

KeyError is raised if the entry asked for cannot be found.</description>

21425

<param name="namename" optional="0">namename</param>

21426

<insert>getgrnam(namename)</insert><dialog title="Insert getgrnam">getgrnam(%0)</dialog><info title="Info window"></info></function>

21427

21428

21429

<description>Return a list of all available group entries, in arbitrary order.</description>

21430

21431

<insert>getgrall()</insert><dialog title="Insert getgrall">getgrall()</dialog><info title="Info window"></info></function>

21432

21433

</group>

21434

21435

<description>Unix

21436

The crypt() function used to check

21437

.

21438

This module implements an interface to the

21439

crypt{3}</description>

21440

21441

<description>word will usually be a user's password as typed at a prompt or in a graphical interface. salt is usually a random

21442

two-character string which will be used to perturb the DES algorithm

21443

in one of 4096 ways. The characters in salt must be in the

21444

set [./a-zA-Z0-9]. Returns the hashed password as a

21445

string, which will be composed of characters from the same alphabet

21446

as the salt (the first two characters represent the salt itself).</description>

21447

21448

<insert>crypt(word, salt salt)</insert><dialog title="Insert crypt">crypt(%0, %1)</dialog><info title="Info window"></info></function>

21449

21450

</group>

21451

21452

<description>Unix %?????????? Anyone????????????

21453

Call C functions in shared objects.

21454

The dl module defines an interface to the

21455

dlopen() function, which is the most common interface on

21456

platforms for handling dynamically linked libraries. It allows

21457

the program to call arbitrary functions in such a library.

21458

This module will not work unless

21459

sizeof(int) == sizeof(long) == sizeof(char *)

21460

If this is not the case, SystemError will be raised on

21461

import.

21462

The dl module defines the following function:

21463

</description>

21464

21465

<description>Open a shared object file, and return a handle. Mode

21466

signifies late binding (RTLD_LAZY) or immediate binding

21467

(RTLD_NOW). Default is RTLD_LAZY. Note that some

21468

systems do not support RTLD_NOW.

21469

Return value is a dlobject.</description>

21470

21471

21472

21473

21474

<description>Dl objects, as returned by open() above, have the

21475

following methods:

21476

</description>

21477

21478

<description>Free all resources, except the memory.</description>

21479

21480

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

21481

21482

21483

<description>Return the pointer for the function named name, as a number, if

21484

it exists in the referenced shared object, otherwise None. This

21485

is useful in code like:

21486

>>> if a.sym('time'): ... a.call('time')

21487

... else: ... time.time()

21488

(Note that this function will return a non-zero number, as zero is the

21489

pointer)</description>

21490

<param name="namename" optional="0">namename</param>

21491

<insert>sym(namename)</insert><dialog title="Insert sym">sym(%0)</dialog><info title="Info window"></info></function>

21492

21493

21494

<description>Call the function named name in the referenced shared object.

21495

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

21496

Python will not like its string mutated.

21497

There must be at most 10 arguments, and arguments not given will be

21498

treated as None. The function's return value must be a C

21499

long, which is a Python integer.</description>

21500

<param name="name" optional="0">name</param><param name="arg1" optional="1">arg1</param><param name="arg2ldots" optional="1">arg2ldots</param>

21501

<insert>call(name, [arg1], [arg2ldots])</insert><dialog title="Insert call">call(%0, %1, %2)</dialog><info title="Info window"></info></function>

21502

21503

</group>

21504

</group>

21505

21506

<description>Unix

21507

The standard ``database'' interface, based on ndbm.

21508

The dbm module provides an interface to the (n)dbm library. Dbm objects behave like mappings

21509

(dictionaries), except that keys and values are always strings.

21510

Printing a dbm object doesn't print the keys and values, and the

21511

items() and values() methods are not supported.

21512

This module can be used with the ``classic'' ndbm interface, the BSD

21513

DB compatibility interface, or the GNU GDBM compatibility interface.

21514

On , the configure script will attempt to locate the

21515

appropriate header file to simplify building this module.

21516

The module defines the following:

21517

{error}

21518

Raised on dbm-specific errors, such as I/O errors.

21519

KeyError is raised for general mapping errors like

21520

specifying an incorrect key.

21521

{library}

21522

Name of the ndbm implementation library used.

21523

</description>

21524

21525

<description>Open a dbm database and return a dbm object. The filename

21526

argument is the name of the database file (without the .dir or

21527

.pag extensions; note that the BSD DB implementation of the

21528

interface will append the extension .db and only create one

21529

file).

21530

The optional flag argument must be one of these values:

21531

{c|l}{code}{Value}{Meaning}

21532

'r'{Open existing database for reading only (default)}

21533

'w'{Open existing database for reading and writing}

21534

'c'{Open database for reading and writing, creating it if

21535

it doesn't exist}

21536

'n'{Always create a new, empty database, open for reading

21537

and writing}

21538

The optional mode argument is the mode of the file, used

21539

only when the database has to be created. It defaults to octal

21540

0666.</description>

21541

<param name="filename" optional="0">filename</param><param name="flag" optional="1">flag</param><param name="mode" optional="1">mode</param>

21542

<insert>open(filename, [flag], [mode])</insert><dialog title="Insert open">open(%0, %1, %2)</dialog><info title="Info window"></info></function>

21543

21544

</group>

21545

21546

<description>Unix

21547

GNU's reinterpretation of dbm.

21548

This module is quite similar to the dbmdbm

21549

module, but uses gdbm instead to provide some additional

21550

functionality. Please note that the file formats created by

21551

gdbm and dbm are incompatible.

21552

The gdbm module provides an interface to the GNU DBM

21553

library. gdbm objects behave like mappings

21554

(dictionaries), except that keys and values are always strings.

21555

Printing a gdbm object doesn't print the keys and values, and

21556

the items() and values() methods are not supported.

21557

The module defines the following constant and functions:

21558

{error}

21559

Raised on gdbm-specific errors, such as I/O errors.

21560

KeyError is raised for general mapping errors like

21561

specifying an incorrect key.

21562

</description>

21563

21564

<description>Open a gdbm database and return a gdbm object. The

21565

filename argument is the name of the database file.

21566

The optional flag argument can be

21567

'r' (to open an existing database for reading only --- default),

21568

'w' (to open an existing database for reading and writing),

21569

'c' (which creates the database if it doesn't exist), or

21570

'n' (which always creates a new empty database).

21571

The following additional characters may be appended to the flag to

21572

control how the database is opened:

21573

'f' --- Open the database in fast mode. Writes to the database

21574

will not be syncronized.

21575

's' --- Synchronized mode. This will cause changes to the database

21576

will be immediately written to the file.

21577

'u' --- Do not lock database. Not all flags are valid for all versions of gdbm. The

21578

module constant open_flags is a string of supported flag

21579

characters. The exception error is raised if an invalid

21580

flag is specified.

21581

The optional mode argument is the mode of the file, used

21582

only when the database has to be created. It defaults to octal

21583

0666.</description>

21584

<param name="filename" optional="0">filename</param><param name="flag" optional="0">flag</param><param name="mode" optional="1">mode</param>

21585

<insert>open(filename, flag, [mode])</insert><dialog title="Insert open">open(%0, %1, %2)</dialog><info title="Info window"></info></function>

21586

21587

21588

<description>It's possible to loop over every key in the database using this method and the nextkey() method. The traversal is ordered by

21589

gdbm's internal hash values, and won't be sorted by the key

21590

values. This method returns the starting key.</description>

21591

21592

<insert>firstkey()</insert><dialog title="Insert firstkey">firstkey()</dialog><info title="Info window"></info></function>

21593

21594

21595

<description>Returns the key that follows key in the traversal. The

21596

following code prints every key in the database db, without

21597

having to create a list in memory that contains them all:

21598

k = db.firstkey()

21599

while k != None:

21600

print k

21601

k = db.nextkey(k)

21602

</description>

21603

<param name="keykey" optional="0">keykey</param>

21604

<insert>nextkey(keykey)</insert><dialog title="Insert nextkey">nextkey(%0)</dialog><info title="Info window"></info></function>

21605

21606

21607

<description>If you have carried out a lot of deletions and would like to shrink

21608

the space used by the gdbm file, this routine will reorganize

21609

the database. gdbm will not shorten the length of a database

21610

file except by using this reorganization; otherwise, deleted file

21611

space will be kept and reused as new (key, value) pairs are added.</description>

21612

21613

<insert>reorganize()</insert><dialog title="Insert reorganize">reorganize()</dialog><info title="Info window"></info></function>

21614

21615

21616

<description>When the database has been opened in fast mode, this method forces any unwritten data to be written to the disk.</description>

21617

21618

21619

21620

</group>

21621

21622

<description>Unix

21623

tty control.

21624

This module provides an interface to the calls for tty I/O

21625

control. For a complete description of these calls, see the or

21626

manual pages. It is only available for those versions

21627

that support termios style tty I/O control (and then

21628

only if configured at installation time).

21629

All functions in this module take a file descriptor fd as their

21630

first argument. This can be an integer file descriptor, such as

21631

returned by sys.stdin.fileno(), or a file object, such as

21632

sys.stdin itself.

21633

This module also defines all the constants needed to work with the

21634

functions provided here; these have the same name as their

21635

counterparts in C. Please refer to your system documentation for more

21636

information on using these terminal control interfaces.

21637

The module defines the following functions:

21638

</description>

21639

21640

<description>Return a list containing the tty attributes for file descriptor

21641

fd, as follows: [iflag, oflag, cflag,

21642

lflag, ispeed, ospeed, cc] where

21643

cc is a list of the tty special characters (each a string of

21644

length 1, except the items with indices VMIN and

21645

VTIME, which are integers when these fields are

21646

defined). The interpretation of the flags and the speeds as well as

21647

the indexing in the cc array must be done using the symbolic

21648

constants defined in the termios

21649

module.</description>

21650

21651

<insert>tcgetattr(fdfd)</insert><dialog title="Insert tcgetattr">tcgetattr(%0)</dialog><info title="Info window"></info></function>

21652

21653

21654

<description>Set the tty attributes for file descriptor fd from the

21655

attributes, which is a list like the one returned by

21656

tcgetattr(). The when argument determines when the

21657

attributes are changed: TCSANOW to change immediately,

21658

TCSADRAIN to change after transmitting all queued output,

21659

or TCSAFLUSH to change after transmitting all queued

21660

output and discarding all queued input.</description>

21661

<param name="fd" optional="0">fd</param><param name="when" optional="0">when</param><param name="attributes attributes" optional="0">attributes attributes</param>

21662

<insert>tcsetattr(fd, when, attributes attributes)</insert><dialog title="Insert tcsetattr">tcsetattr(%0, %1, %2)</dialog><info title="Info window"></info></function>

21663

21664

21665

<description>Send a break on file descriptor fd. A zero duration sends

21666

a break for 0.25--0.5 seconds; a nonzero duration has a system

21667

dependent meaning.</description>

21668

<param name="fd" optional="0">fd</param><param name="duration duration" optional="0">duration duration</param>

21669

<insert>tcsendbreak(fd, duration duration)</insert><dialog title="Insert tcsendbreak">tcsendbreak(%0, %1)</dialog><info title="Info window"></info></function>

21670

21671

21672

<description>Wait until all output written to file descriptor fd has been

21673

transmitted.</description>

21674

21675

<insert>tcdrain(fdfd)</insert><dialog title="Insert tcdrain">tcdrain(%0)</dialog><info title="Info window"></info></function>

21676

21677

21678

<description>Discard queued data on file descriptor fd. The queue

21679

selector specifies which queue: TCIFLUSH for the input

21680

queue, TCOFLUSH for the output queue, or

21681

TCIOFLUSH for both queues.</description>

21682

<param name="fd" optional="0">fd</param><param name="queue queue" optional="0">queue queue</param>

21683

<insert>tcflush(fd, queue queue)</insert><dialog title="Insert tcflush">tcflush(%0, %1)</dialog><info title="Info window"></info></function>

21684

21685

21686

<description>Suspend or resume input or output on file descriptor fd. The

21687

action argument can be TCOOFF to suspend output,

21688

TCOON to restart output, TCIOFF to suspend

21689

input, or TCION to restart input.</description>

21690

<param name="fd" optional="0">fd</param><param name="action action" optional="0">action action</param>

21691

<insert>tcflow(fd, action action)</insert><dialog title="Insert tcflow">tcflow(%0, %1)</dialog><info title="Info window"></info></function>

21692

21693

21694

</group>

21695

</group>

21696

21697

<description>Unix

21698

Utility functions that perform common terminal control

21699

operations.

21700

The tty module defines functions for putting the tty into

21701

cbreak and raw modes.

21702

Because it requires the termios module, it will work

21703

only on .

21704

The tty module defines the following functions:

21705

</description>

21706

21707

<description>Change the mode of the file descriptor fd to raw. If when

21708

is omitted, it defaults to TERMIOS.TCAFLUSH, and is passed

21709

to termios.tcsetattr().</description>

21710

21711

<insert>setraw(fd, [when])</insert><dialog title="Insert setraw">setraw(%0, %1)</dialog><info title="Info window"></info></function>

21712

21713

21714

<description>Change the mode of file descriptor fd to cbreak. If when

21715

is omitted, it defaults to TERMIOS.TCAFLUSH, and is passed

21716

to termios.tcsetattr().</description>

21717

21718

<insert>setcbreak(fd, [when])</insert><dialog title="Insert setcbreak">setcbreak(%0, %1)</dialog><info title="Info window"></info></function>

21719

21720

</group>

21721

21722

<description>IRIX, Linux

21723

Pseudo-Terminal Handling for SGI and Linux.

21724

The pty module defines operations for handling the

21725

pseudo-terminal concept: starting another process and being able to

21726

write to and read from its controlling terminal programmatically.

21727

Because pseudo-terminal handling is highly platform dependant, there

21728

is code to do it only for SGI and Linux. (The Linux code is supposed

21729

to work on other platforms, but hasn't been tested yet.)

21730

The pty module defines the following functions:

21731

</description>

21732

21733

<description>Fork. Connect the child's controlling terminal to a pseudo-terminal.

21734

Return value is (pid, fd). Note that the child gets pid 0, and the fd is invalid. The parent's

21735

return value is the pid of the child, and fd is a file

21736

descriptor connected to the child's controlling terminal (and also

21737

to the child's standard input and output).</description>

21738

21739

21740

21741

21742

<description>Open a new pseudo-terminal pair, using os.openpty() if

21743

possible, or emulation code for SGI and generic systems.

21744

Return a pair of file descriptors (master, slave),

21745

for the master and the slave end, respectively.</description>

21746

21747

<insert>openpty()</insert><dialog title="Insert openpty">openpty()</dialog><info title="Info window"></info></function>

21748

21749

21750

<description>Spawn a process, and connect its controlling terminal with the current process's standard io. This is often used to baffle programs which

21751

insist on reading from the controlling terminal.

21752

The functions master_read and stdin_read should be

21753

functions which read from a file-descriptor. The defaults try to read

21754

1024 bytes each time they are called.</description>

21755

<param name="argv" optional="0">argv</param><param name="master_read" optional="1">master_read</param><param name="stdin_read" optional="1">stdin_read</param>

21756

<insert>spawn(argv, [master_read], [stdin_read])</insert><dialog title="Insert spawn">spawn(%0, %1, %2)</dialog><info title="Info window"></info></function>

21757

21758

</group>

21759

21760

<description>Unix

21761

The fcntl() and ioctl() system calls.

21762

This module performs file control and I/O control on file descriptors.

21763

It is an interface to the fcntl() and ioctl()

21764

routines.

21765

All functions in this module take a file descriptor fd as their

21766

first argument. This can be an integer file descriptor, such as

21767

returned by sys.stdin.fileno(), or a file object, such as

21768

sys.stdin itself, which provides a fileno() which

21769

returns a genuine file descriptor.

21770

The module defines the following functions:

21771

</description>

21772

21773

<description>Perform the requested operation on file descriptor fd (file

21774

objects providing a fileno() method are accepted as well).

21775

The operation is defined by op and is operating system

21776

dependent. These codes are also found in the fcntl

21777

module. The argument arg is optional, and defaults to the

21778

integer value 0. When present, it can either be an integer

21779

value, or a string. With the argument missing or an integer value,

21780

the return value of this function is the integer return value of the

21781

C fcntl() call. When the argument is a string it

21782

represents a binary structure, e.g. by

21783

struct.pack(). The binary data is copied to a buffer

21784

whose address is passed to the C fcntl() call. The

21785

return value after a successful call is the contents of the buffer,

21786

converted to a string object. The length of the returned string

21787

will be the same as the length of the arg argument. This is

21788

limited to 1024 bytes. If the information returned in the buffer by

21789

the operating system is larger than 1024 bytes, this is most likely

21790

to result in a segmentation violation or a more subtle data

21791

corruption.

21792

If the fcntl() fails, an IOError is

21793

raised.</description>

21794

21795

<insert>fcntl(fd, op, [arg])</insert><dialog title="Insert fcntl">fcntl(%0, %1, %2)</dialog><info title="Info window"></info></function>

21796

21797

21798

<description>This function is identical to the fcntl() function,

21799

except that the operations are typically defined in the library

21800

module termios and the argument handling is even more

21801

complicated.

21802

The parameter arg can be one of an integer, absent (treated

21803

identically to the integer 0), an object supporting the

21804

read-only buffer interface (most likely a plain Python string) or an

21805

object supporting the read-write buffer interface.

21806

In all but the last case, behaviour is as for the fcntl()

21807

function.

21808

If a mutable buffer is passed, then the behaviour is determined by

21809

the value of the mutate_flag parameter.

21810

If it is false, the buffer's mutability is ignored and behaviour is

21811

as for a read-only buffer, except that the 1024 byte limit mentioned

21812

above is avoided -- so long as the buffer you pass is longer than

21813

what the operating system wants to put there, things should work.

21814

If mutate_flag is true, then the buffer is (in effect) passed

21815

to the underlying ioctl() system call, the latter's

21816

return code is passed back to the calling Python, and the buffer's

21817

new contents reflect the action of the ioctl. This is a

21818

slight simplification, because if the supplied buffer is less than

21819

1024 bytes long it is first copied into a static buffer 1024 bytes

21820

long which is then passed to ioctl and copied back into

21821

the supplied buffer.

21822

If mutate_flag is not supplied, then in 2.3 it defaults to

21823

false. This is planned to change over the next few Python versions:

21824

in 2.4 failing to supply mutate_flag will get a warning but

21825

the same behavior and in versions later than 2.5 it will default to

21826

true.

21827

An example:

21828

>>> import array, fcntl, struct, termios, os

21829

>>> os.getpgrp()

21830

13341

21831

>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0]

21832

13341

21833

>>> buf = array.array('h', [0])

21834

>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)

21835

0

21836

>>> buf

21837

array('h', [13341])

21838

</description>

21839

<param name="fd" optional="0">fd</param><param name="op" optional="0">op</param><param name="arg" optional="1">arg</param><param name="mutate_flag" optional="1">mutate_flag</param>

21840

<insert>ioctl(fd, op, [arg], [mutate_flag])</insert><dialog title="Insert ioctl">ioctl(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

21841

21842

21843

<description>Perform the lock operation op on file descriptor fd (file

21844

objects providing a fileno() method are accepted as well).

21845

See the manual flock{3} for details. (On some

21846

systems, this function is emulated using fcntl().)</description>

21847

21848

<insert>flock(fd, op op)</insert><dialog title="Insert flock">flock(%0, %1)</dialog><info title="Info window"></info></function>

21849

21850

21851

<description>This is essentially a wrapper around the fcntl() locking

21852

calls. fd is the file descriptor of the file to lock or unlock,

21853

and operation is one of the following values:

21854

LOCK_UN -- unlock

21855

LOCK_SH -- acquire a shared lock

21856

LOCK_EX -- acquire an exclusive lock

21857

When operation is LOCK_SH or LOCK_EX, it

21858

can also be bit-wise OR'd with LOCK_NB to avoid blocking on

21859

lock acquisition. If LOCK_NB is used and the lock cannot

21860

be acquired, an IOError will be raised and the exception

21861

will have an errno attribute set to EACCES or

21862

EAGAIN (depending on the operating system; for portability,

21863

check for both values). On at least some systems, LOCK_EX

21864

can only be used if the file descriptor refers to a file opened for

21865

writing.

21866

length is the number of bytes to lock, start is the byte

21867

offset at which the lock starts, relative to whence, and

21868

whence is as with fileobj.seek(), specifically:

21869

0 -- relative to the start of the file

21870

(SEEK_SET)

21871

1 -- relative to the current buffer position

21872

(SEEK_CUR)

21873

2 -- relative to the end of the file

21874

(SEEK_END)

21875

The default for start is 0, which means to start at the

21876

beginning of the file. The default for length is 0 which means

21877

to lock to the end of the file. The default for whence is also

21878

0.</description>

21879

<param name="fd" optional="0">fd</param><param name="operation" optional="0">operation</param><param name="len" optional="0">len</param><param name="start" optional="1">start</param><param name="whence" optional="1">whence</param>

21880

<insert>lockf(fd, operation, len, [start], [whence])</insert><dialog title="Insert lockf">lockf(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

21881

21882

</group>

21883

21884

<description>Unix

21885

A Python interface to pipelines.

21886

The pipes module defines a class to abstract the concept of

21887

a pipeline --- a sequence of convertors from one file to another.

21888

Because the module uses /bin/sh command lines, a or

21889

compatible shell for os.system() and os.popen()

21890

is required.

21891

The pipes module defines the following class:

21892

</description>

21893

21894

<description>An abstraction of a pipeline.</description>

21895

21896

<insert>Template()</insert><dialog title="Insert Template">Template()</dialog><info title="Info window"></info></function>

21897

21898

21899

<description>Template objects following methods:

21900

</description>

21901

21902

<description>Restore a pipeline template to its initial state.</description>

21903

21904

<insert>reset()</insert><dialog title="Insert reset">reset()</dialog><info title="Info window"></info></function>

21905

21906

21907

<description>Return a new, equivalent, pipeline template.</description>

21908

21909

<insert>clone()</insert><dialog title="Insert clone">clone()</dialog><info title="Info window"></info></function>

21910

21911

21912

<description>If flag is true, turn debugging on. Otherwise, turn debugging

21913

off. When debugging is on, commands to be executed are printed, and

21914

the shell is given set -x command to be more verbose.</description>

21915

<param name="flagflag" optional="0">flagflag</param>

21916

<insert>debug(flagflag)</insert><dialog title="Insert debug">debug(%0)</dialog><info title="Info window"></info></function>

21917

21918

21919

<description>Append a new action at the end. The cmd variable must be a valid

21920

bourne shell command. The kind variable consists of two letters.

21921

The first letter can be either of '-' (which means the command

21922

reads its standard input), 'f' (which means the commands reads

21923

a given file on the command line) or '.' (which means the commands

21924

reads no input, and hence must be first.)

21925

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

21926

the command does not write anything, and hence must be last.)</description>

21927

21928

<insert>append(cmd, kind kind)</insert><dialog title="Insert append">append(%0, %1)</dialog><info title="Info window"></info></function>

21929

21930

21931

<description>Add a new action at the beginning. See append() for explanations

21932

of the arguments.</description>

21933

21934

<insert>prepend(cmd, kind kind)</insert><dialog title="Insert prepend">prepend(%0, %1)</dialog><info title="Info window"></info></function>

21935

21936

21937

<description>Return a file-like object, open to file, but read from or

21938

written to by the pipeline. Note that only one of 'r',

21939

'w' may be given.</description>

21940

21941

21942

21943

21944

<description>Copy infile to outfile through the pipe.</description>

21945

<param name="infile" optional="0">infile</param><param name="outfile outfile" optional="0">outfile outfile</param>

21946

<insert>copy(infile, outfile outfile)</insert><dialog title="Insert copy">copy(%0, %1)</dialog><info title="Info window"></info></function>

21947

21948

</group>

21949

</group>

21950

21951

<description>Unix

21952

A file-like object with support for locking.

21953

1.5{The locking operation that this module provides is

21954

done better and more portably by the

21955

fcntl.lockf() call.

21956

(in module fcntl){lockf()}}

21957

This module implements some additional functionality over the built-in

21958

file objects. In particular, it implements file locking, control over

21959

the file flags, and an easy interface to duplicate the file object.

21960

The module defines a new file object, the posixfile object. It

21961

has all the standard file object methods and adds the methods

21962

described below. This module only works for certain flavors of

21963

, since it uses fcntl.fcntl() for file locking.%

21964

(in module fcntl){fcntl()}

21965

To instantiate a posixfile object, use the open() function

21966

in the posixfile module. The resulting object looks and

21967

feels roughly the same as a standard file object.

21968

The posixfile module defines the following constants:

21969

{SEEK_SET}

21970

Offset is calculated from the start of the file.

21971

{SEEK_CUR}

21972

Offset is calculated from the current position in the file.

21973

{SEEK_END}

21974

Offset is calculated from the end of the file.

21975

The posixfile module defines the following functions:

21976

</description>

21977

21978

<description>Create a new posixfile object with the given filename and mode. The

21979

filename, mode and bufsize arguments are

21980

interpreted the same way as by the built-in open()

21981

function.</description>

21982

<param name="filename" optional="0">filename</param><param name="mode" optional="1">mode</param><param name="bufsize" optional="1">bufsize</param>

21983

<insert>open(filename, [mode], [bufsize])</insert><dialog title="Insert open">open(%0, %1, %2)</dialog><info title="Info window"></info></function>

21984

21985

21986

<description>Create a new posixfile object with the given standard file object.

21987

The resulting object has the same filename and mode as the original

21988

file object.</description>

21989

<param name="fileobjectfileobject" optional="0">fileobjectfileobject</param>

21990

<insert>fileopen(fileobjectfileobject)</insert><dialog title="Insert fileopen">fileopen(%0)</dialog><info title="Info window"></info></function>

21991

21992

21993

<description>Lock the specified section of the file that the file object is

21994

referring to. The format is explained

21995

below in a table. The len argument specifies the length of the

21996

section that should be locked. The default is 0. start

21997

specifies the starting offset of the section, where the default is

21998

0. The whence argument specifies where the offset is

21999

relative to. It accepts one of the constants SEEK_SET,

22000

SEEK_CUR or SEEK_END. The default is

22001

SEEK_SET. For more information about the arguments refer

22002

to the fcntl{2} manual page on your system.</description>

22003

<param name="fmt" optional="0">fmt</param><param name="len" optional="0">len</param><param name="start" optional="1">start</param><param name="whence" optional="1">whence</param>

22004

<insert>lock(fmt, len, [start], [whence])</insert><dialog title="Insert lock">lock(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

22005

22006

22007

<description>Set the specified flags for the file that the file object is referring

22008

to. The new flags are ORed with the old flags, unless specified

22009

otherwise. The format is explained below in a table. Without

22010

the flags argument

22011

a string indicating the current flags is returned (this is

22012

the same as the ? modifier). For more information about the

22013

flags refer to the fcntl{2} manual page on your system.</description>

22014

<param name="flags" optional="0">flags</param>

22015

<insert>flags(flags)</insert><dialog title="Insert flags">flags(%0)</dialog><info title="Info window"></info></function>

22016

22017

22018

<description>Duplicate the file object and the underlying file pointer and file

22019

descriptor. The resulting object behaves as if it were newly

22020

opened.</description>

22021

22022

22023

22024

22025

<description>Duplicate the file object and the underlying file pointer and file

22026

descriptor. The new object will have the given file descriptor.

22027

Otherwise the resulting object behaves as if it were newly opened.</description>

22028

22029

22030

22031

22032

<description>Return the standard file object that the posixfile object is based

22033

on. This is sometimes necessary for functions that insist on a

22034

standard file object.</description>

22035

22036

22037

22038

</group>

22039

22040

<description>Unix

22041

An interface to provide resource usage information on

22042

the current process.

22043

This module provides basic mechanisms for measuring and controlling

22044

system resources utilized by a program.

22045

Symbolic constants are used to specify particular system resources and

22046

to request usage information about either the current process or its

22047

children.

22048

A single exception is defined for errors:

22049

{error}

22050

The functions described below may raise this error if the underlying

22051

system call failures unexpectedly.

22052

</description>

22053

22054

<description>Resources usage can be limited using the setrlimit() function

22055

described below. Each resource is controlled by a pair of limits: a

22056

soft limit and a hard limit. The soft limit is the current limit, and

22057

may be lowered or raised by a process over time. The soft limit can

22058

never exceed the hard limit. The hard limit can be lowered to any

22059

value greater than the soft limit, but not raised. (Only processes with

22060

the effective UID of the super-user can raise a hard limit.)

22061

The specific resources that can be limited are system dependent. They

22062

are described in the getrlimit{2} man page. The resources

22063

listed below are supported when the underlying operating system

22064

supports them; resources which cannot be checked or controlled by the

22065

operating system are not defined in this module for those platforms.

22066

</description>

22067

22068

<description>Returns a tuple (soft, hard) with the current

22069

soft and hard limits of resource. Raises ValueError if

22070

an invalid resource is specified, or error if the

22071

underyling system call fails unexpectedly.</description>

22072

<param name="resourceresource" optional="0">resourceresource</param>

22073

<insert>getrlimit(resourceresource)</insert><dialog title="Insert getrlimit">getrlimit(%0)</dialog><info title="Info window"></info></function>

22074

22075

22076

<description>Sets new limits of consumption of resource. The limits

22077

argument must be a tuple (soft, hard) of two

22078

integers describing the new limits. A value of -1 can be used to

22079

specify the maximum possible upper limit.

22080

Raises ValueError if an invalid resource is specified,

22081

if the new soft limit exceeds the hard limit, or if a process tries

22082

to raise its hard limit (unless the process has an effective UID of

22083

super-user). Can also raise error if the underyling

22084

system call fails.</description>

22085

<param name="resource" optional="0">resource</param><param name="limits limits" optional="0">limits limits</param>

22086

<insert>setrlimit(resource, limits limits)</insert><dialog title="Insert setrlimit">setrlimit(%0, %1)</dialog><info title="Info window"></info></function>

22087

22088

</group>

22089

22090

<description>These functions are used to retrieve resource usage information:

22091

</description>

22092

22093

<description>This function returns an object that describes the resources

22094

consumed by either the current process or its children, as specified

22095

by the who parameter. The who parameter should be

22096

specified using one of the RUSAGE_* constants described

22097

below.

22098

The fields of the return value each describe how a particular system

22099

resource has been used, e.g. amount of time spent running is user mode

22100

or number of times the process was swapped out of main memory. Some

22101

values are dependent on the clock tick internal, e.g. the amount of

22102

memory the process is using.

22103

For backward compatibility, the return value is also accessible as

22104

a tuple of 16 elements.

22105

The fields ru_utime and ru_stime of the return value

22106

are floating point values representing the amount of time spent

22107

executing in user mode and the amount of time spent executing in system

22108

mode, respectively. The remaining values are integers. Consult the

22109

getrusage{2} man page for detailed information about these

22110

values. A brief summary is presented here:

22111

{r|l|l}{code}{Index}{Field}{Resource}

22112

0{ru_utime}{time in user mode (float)}

22113

1{ru_stime}{time in system mode (float)}

22114

2{ru_maxrss}{maximum resident set size}

22115

3{ru_ixrss}{shared memory size}

22116

4{ru_idrss}{unshared memory size}

22117

5{ru_isrss}{unshared stack size}

22118

6{ru_minflt}{page faults not requiring I/O}

22119

7{ru_majflt}{page faults requiring I/O}

22120

8{ru_nswap}{number of swap outs}

22121

9{ru_inblock}{block input operations}

22122

10{ru_oublock}{block output operations}

22123

11{ru_msgsnd}{messages sent}

22124

12{ru_msgrcv}{messages received}

22125

13{ru_nsignals}{signals received}

22126

14{ru_nvcsw}{voluntary context switches}

22127

15{ru_nivcsw}{involuntary context switches}

22128

This function will raise a ValueError if an invalid

22129

who parameter is specified. It may also raise

22130

error exception in unusual circumstances.

22131

Changed in version 2.3: Added access to values as attributes of the

22132

returned object</description>

22133

<param name="whowho" optional="0">whowho</param>

22134

<insert>getrusage(whowho)</insert><dialog title="Insert getrusage">getrusage(%0)</dialog><info title="Info window"></info></function>

22135

22136

22137

<description>Returns the number of bytes in a system page. (This need not be the

22138

same as the hardware page size.) This function is useful for

22139

determining the number of bytes of memory a process is using. The

22140

third element of the tuple returned by getrusage() describes

22141

memory usage in pages; multiplying by page size produces number of

22142

bytes.</description>

22143

22144

<insert>getpagesize()</insert><dialog title="Insert getpagesize">getpagesize()</dialog><info title="Info window"></info></function>

22145

22146

</group>

22147

</group>

22148

22149

<description>UNIX

22150

Interface to Sun's NIS (Yellow Pages) library.

22151

The nis module gives a thin wrapper around the NIS library, useful

22152

for central administration of several hosts.

22153

Because NIS exists only on systems, this module is

22154

only available for .

22155

The nis module defines the following functions:

22156

</description>

22157

22158

<description>Return the match for key in map mapname, or raise an

22159

error (nis.error) if there is none.

22160

Both should be strings, key is 8-bit clean.

22161

Return value is an arbitrary array of bytes (may contain NULL

22162

and other joys).

22163

Note that mapname is first checked if it is an alias to another

22164

name.</description>

22165

<param name="key" optional="0">key</param><param name="mapname mapname" optional="0">mapname mapname</param>

22166

<insert>match(key, mapname mapname)</insert><dialog title="Insert match">match(%0, %1)</dialog><info title="Info window"></info></function>

22167

22168

22169

<description>Return a dictionary mapping key to value such that

22170

match(key, mapname)==value.

22171

Note that both keys and values of the dictionary are arbitrary

22172

arrays of bytes.

22173

Note that mapname is first checked if it is an alias to another

22174

name.</description>

22175

<param name="mapnamemapname" optional="0">mapnamemapname</param>

22176

<insert>cat(mapnamemapname)</insert><dialog title="Insert cat">cat(%0)</dialog><info title="Info window"></info></function>

22177

22178

22179

<description>Return a list of all valid maps.</description>

22180

22181

22182

22183

</group>

22184

22185

<description>Unix

22186

An interface to the library routines.

22187

This module provides an interface to the syslog library

22188

routines. Refer to the manual pages for a detailed description

22189

of the syslog facility.

22190

The module defines the following functions:

22191

</description>

22192

22193

<description>Send the string message to the system logger. A trailing

22194

newline is added if necessary. Each message is tagged with a priority

22195

composed of a facility and a level. The optional

22196

priority argument, which defaults to LOG_INFO,

22197

determines the message priority. If the facility is not encoded in

22198

priority using logical-or (LOG_INFO | LOG_USER), the

22199

value given in the openlog() call is used.</description>

22200

<param name="priority" optional="0">priority</param><param name="message message" optional="1">message message</param>

22201

<insert>syslog(priority, [message message])</insert><dialog title="Insert syslog">syslog(%0, %1)</dialog><info title="Info window"></info></function>

22202

22203

22204

<description>Logging options other than the defaults can be set by explicitly

22205

opening the log file with openlog() prior to calling

22206

syslog(). The defaults are (usually) ident =

22207

'syslog', logopt = 0, facility =

22208

LOG_USER. The ident argument is a string which is

22209

prepended to every message. The optional logopt argument is a

22210

bit field - see below for possible values to combine. The optional

22211

facility argument sets the default facility for messages which

22212

do not have a facility explicitly encoded.</description>

22213

<param name="ident" optional="0">ident</param><param name="logopt" optional="1">logopt</param><param name="facility" optional="1">facility</param>

22214

<insert>openlog(ident, [logopt], [facility])</insert><dialog title="Insert openlog">openlog(%0, %1, %2)</dialog><info title="Info window"></info></function>

22215

22216

22217

<description>Close the log file.</description>

22218

22219

<insert>closelog()</insert><dialog title="Insert closelog">closelog()</dialog><info title="Info window"></info></function>

22220

22221

22222

<description>Set the priority mask to maskpri and return the

22223

previous mask value. Calls to syslog() with a priority

22224

level not set in maskpri are ignored. The default is to log all

22225

priorities. The function LOG_MASK(pri) calculates the

22226

mask for the individual priority pri. The function

22227

LOG_UPTO(pri) calculates the mask for all priorities up

22228

to and including pri.</description>

22229

<param name="maskprimaskpri" optional="0">maskprimaskpri</param>

22230

<insert>setlogmask(maskprimaskpri)</insert><dialog title="Insert setlogmask">setlogmask(%0)</dialog><info title="Info window"></info></function>

22231

22232

</group>

22233

22234

<description>Unix

22235

Utility functions for running external commands.

22236

The commands module contains wrapper functions for

22237

os.popen() which take a system command as a string and

22238

return any output generated by the command and, optionally, the exit

22239

status.

22240

The commands module defines the following functions:

22241

</description>

22242

22243

<description>Execute the string cmd in a shell with os.popen() and

22244

return a 2-tuple (status, output). cmd is

22245

actually run as { cmd ; } 2>1, so that the returned

22246

output will contain output or error messages. A trailing newline is

22247

stripped from the output. The exit status for the command can be

22248

interpreted according to the rules for the C function

22249

wait().</description>

22250

<param name="cmdcmd" optional="0">cmdcmd</param>

22251

<insert>getstatusoutput(cmdcmd)</insert><dialog title="Insert getstatusoutput">getstatusoutput(%0)</dialog><info title="Info window"></info></function>

22252

22253

22254

<description>Like getstatusoutput(), except the exit status is ignored

22255

and the return value is a string containing the command's output.</description>

22256

<param name="cmdcmd" optional="0">cmdcmd</param>

22257

<insert>getoutput(cmdcmd)</insert><dialog title="Insert getoutput">getoutput(%0)</dialog><info title="Info window"></info></function>

22258

22259

22260

<description>Return the output of ls -ld file as a string. This

22261

function uses the getoutput() function, and properly

22262

escapes backslashes and dollar signs in the argument.</description>

22263

<param name="filefile" optional="0">filefile</param>

22264

<insert>getstatus(filefile)</insert><dialog title="Insert getstatus">getstatus(%0)</dialog><info title="Info window"></info></function>

22265

22266

</group>

22267

</group>

22268

22269

22270

</group>

22271

</group>

22272

22273

22274

<description>Profiler Introduction

22275

A profiler is a program that describes the run time performance

22276

of a program, providing a variety of statistics. This documentation

22277

describes the profiler functionality provided in the modules

22278

profile and pstats. This profiler provides

22279

deterministic profiling of any Python programs. It also

22280

provides a series of report generation tools to allow users to rapidly

22281

examine the results of a profile operation.

22282

</description>

22283

22284

<description>This function takes a single argument that has can be passed to the

22285

exec statement, and an optional file name. In all cases this

22286

routine attempts to exec its first argument, and gather profiling

22287

statistics from the execution. If no file name is present, then this

22288

function automatically prints a simple profiling report, sorted by the

22289

standard name string (file/line/function-name) that is presented in

22290

each line. The following is a typical output from such a call:

22291

main()

22292

2706 function calls (2004 primitive calls) in 4.504 CPU seconds

22293

Ordered by: standard name

22294

ncalls tottime percall cumtime percall filename:lineno(function)

22295

2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects)

22296

43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate)

22297

...

22298

The first line indicates that this profile was generated by the call:

22299

profile.run('main()'), and hence the exec'ed string is

22300

'main()'. The second line indicates that 2706 calls were

22301

monitored. Of those calls, 2004 were primitive. We define

22302

primitive to mean that the call was not induced via recursion.

22303

The next line: Ordered by: name, indicates that

22304

the text string in the far right column was used to sort the output.

22305

The column headings include:

22306

[ncalls ]

22307

for the number of calls,

22308

[tottime ]

22309

for the total time spent in the given function (and excluding time

22310

made in calls to sub-functions),

22311

[percall ]

22312

is the quotient of tottime divided by ncalls

22313

[cumtime ]

22314

is the total time spent in this and all subfunctions (from invocation

22315

till exit). This figure is accurate even for recursive

22316

functions.

22317

[percall ]

22318

is the quotient of cumtime divided by primitive calls

22319

[filename:lineno(function) ]

22320

provides the respective data of each function

22321

When there are two numbers in the first column (for example,

22322

43/3), then the latter is the number of primitive calls, and

22323

the former is the actual number of calls. Note that when the function

22324

does not recurse, these two values are the same, and only the single

22325

figure is printed.</description>

22326

<param name="string" optional="0">string</param><param name="filename" optional="1">filename</param><param name="..." optional="1">...</param>

22327

<insert>run(string, [filename], [...])</insert><dialog title="Insert run">run(%0, %1, %2)</dialog><info title="Info window"></info></function>

22328

22329

22330

<description>This class constructor creates an instance of a ``statistics object''

22331

from a filename (or set of filenames). Stats objects are

22332

manipulated by methods, in order to print useful reports.

22333

The file selected by the above constructor must have been created by

22334

the corresponding version of profile. To be specific, there is

22335

no file compatibility guaranteed with future versions of this

22336

profiler, and there is no compatibility with files produced by other

22337

profilers (such as the old system profiler).

22338

If several files are provided, all the statistics for identical

22339

functions will be coalesced, so that an overall view of several

22340

processes can be considered in a single report. If additional files

22341

need to be combined with data in an existing Stats object, the

22342

add() method can be used.</description>

22343

<param name="filename" optional="0">filename</param><param name="..." optional="1">...</param>

22344

<insert>Stats(filename, [...])</insert><dialog title="Insert Stats">Stats(%0, %1)</dialog><info title="Info window"></info></function>

22345

22346

22347

<description>Stats objects have the following methods:

22348

</description>

22349

22350

<description>This method for the Stats class removes all leading path

22351

information from file names. It is very useful in reducing the size

22352

of the printout to fit within (close to) 80 columns. This method

22353

modifies the object, and the stripped information is lost. After

22354

performing a strip operation, the object is considered to have its

22355

entries in a ``random'' order, as it was just after object

22356

initialization and loading. If strip_dirs() causes two

22357

function names to be indistinguishable (they are on the same

22358

line of the same filename, and have the same function name), then the

22359

statistics for these two entries are accumulated into a single entry.</description>

22360

22361

<insert>strip_dirs()</insert><dialog title="Insert strip_dirs">strip_dirs()</dialog><info title="Info window"></info></function>

22362

22363

22364

<description>This method of the Stats class accumulates additional

22365

profiling information into the current profiling object. Its

22366

arguments should refer to filenames created by the corresponding

22367

version of profile.run(). Statistics for identically named

22368

(re: file, line, name) functions are automatically accumulated into

22369

single function statistics.</description>

22370

<param name="filename" optional="0">filename</param><param name="..." optional="1">...</param>

22371

<insert>add(filename, [...])</insert><dialog title="Insert add">add(%0, %1)</dialog><info title="Info window"></info></function>

22372

22373

22374

<description>Save the data loaded into the Stats object to a file named

22375

filename. The file is created if it does not exist, and is

22376

overwritten if it already exists. This is equivalent to the method of

22377

the same name on the profile.Profile class.

22378

New in version 2.3</description>

22379

<param name="filenamefilename" optional="0">filenamefilename</param>

22380

<insert>dump_stats(filenamefilename)</insert><dialog title="Insert dump_stats">dump_stats(%0)</dialog><info title="Info window"></info></function>

22381

22382

22383

<description>This method modifies the Stats object by sorting it according

22384

to the supplied criteria. The argument is typically a string

22385

identifying the basis of a sort (example: 'time' or

22386

'name').

22387

When more than one key is provided, then additional keys are used as

22388

secondary criteria when there is equality in all keys selected

22389

before them. For example, sort_stats('name', 'file') will sort

22390

all the entries according to their function name, and resolve all ties

22391

(identical function names) by sorting by file name.

22392

Abbreviations can be used for any key names, as long as the

22393

abbreviation is unambiguous. The following are the keys currently

22394

defined:

22395

{l|l}{code}{Valid Arg}{Meaning}

22396

'calls'{call count}

22397

'cumulative'{cumulative time}

22398

'file'{file name}

22399

'module'{file name}

22400

'pcalls'{primitive call count}

22401

'line'{line number}

22402

'name'{function name}

22403

'nfl'{name/file/line}

22404

'stdname'{standard name}

22405

'time'{internal time}

22406

Note that all sorts on statistics are in descending order (placing

22407

most time consuming items first), where as name, file, and line number

22408

searches are in ascending order (alphabetical). The subtle

22409

distinction between 'nfl' and 'stdname' is that the

22410

standard name is a sort of the name as printed, which means that the

22411

embedded line numbers get compared in an odd way. For example, lines

22412

3, 20, and 40 would (if the file names were the same) appear in the

22413

string order 20, 3 and 40. In contrast, 'nfl' does a numeric

22414

compare of the line numbers. In fact, sort_stats('nfl') is the

22415

same as sort_stats('name', 'file', 'line').

22416

For compatibility with the old profiler, the numeric arguments

22417

-1, 0, 1, and 2 are permitted. They are

22418

interpreted as 'stdname', 'calls', 'time', and

22419

'cumulative' respectively. If this old style format (numeric)

22420

is used, only one sort key (the numeric key) will be used, and

22421

additional arguments will be silently ignored.</description>

22422

22423

<insert>sort_stats(key, [...])</insert><dialog title="Insert sort_stats">sort_stats(%0, %1)</dialog><info title="Info window"></info></function>

22424

22425

22426

<description>This method for the Stats class reverses the ordering of the basic

22427

list within the object. This method is provided primarily for

22428

compatibility with the old profiler. Its utility is questionable

22429

now that ascending vs descending order is properly selected based on

22430

the sort key of choice.</description>

22431

22432

<insert>reverse_order()</insert><dialog title="Insert reverse_order">reverse_order()</dialog><info title="Info window"></info></function>

22433

22434

22435

<description>This method for the Stats class prints out a report as described

22436

in the profile.run() definition.

22437

The order of the printing is based on the last sort_stats()

22438

operation done on the object (subject to caveats in add() and

22439

strip_dirs()).

22440

The arguments provided (if any) can be used to limit the list down to

22441

the significant entries. Initially, the list is taken to be the

22442

complete set of profiled functions. Each restriction is either an

22443

integer (to select a count of lines), or a decimal fraction between

22444

0.0 and 1.0 inclusive (to select a percentage of lines), or a regular

22445

expression (to pattern match the standard name that is printed; as of

22446

Python 1.5b1, this uses the Perl-style regular expression syntax

22447

defined by the re module). If several restrictions are

22448

provided, then they are applied sequentially. For example:

22449

print_stats(.1, 'foo:')

22450

would first limit the printing to first 10% of list, and then only

22451

print functions that were part of filename .*foo:. In

22452

contrast, the command:

22453

print_stats('foo:', .1)

22454

would limit the list to all functions having file names .*foo:,

22455

and then proceed to only print the first 10% of them.</description>

22456

<param name="restriction" optional="0">restriction</param><param name="moreargs" optional="1">moreargs</param>

22457

<insert>print_stats(restriction, [moreargs])</insert><dialog title="Insert print_stats">print_stats(%0, %1)</dialog><info title="Info window"></info></function>

22458

22459

22460

<description>This method for the Stats class prints a list of all functions

22461

that called each function in the profiled database. The ordering is

22462

identical to that provided by print_stats(), and the definition

22463

of the restricting argument is also identical. For convenience, a

22464

number is shown in parentheses after each caller to show how many

22465

times this specific call was made. A second non-parenthesized number

22466

is the cumulative time spent in the function at the right.</description>

22467

<param name="restriction" optional="0">restriction</param><param name="moreargs" optional="1">moreargs</param>

22468

<insert>print_callers(restriction, [moreargs])</insert><dialog title="Insert print_callers">print_callers(%0, %1)</dialog><info title="Info window"></info></function>

22469

22470

22471

<description>This method for the Stats class prints a list of all function

22472

that were called by the indicated function. Aside from this reversal

22473

of direction of calls (re: called vs was called by), the arguments and

22474

ordering are identical to the print_callers() method.</description>

22475

<param name="restriction" optional="0">restriction</param><param name="moreargs" optional="1">moreargs</param>

22476

<insert>print_callees(restriction, [moreargs])</insert><dialog title="Insert print_callees">print_callees(%0, %1)</dialog><info title="Info window"></info></function>

22477

22478

22479

<description>1.5.1{This is not needed in modern versions of

22480

Python.

22481

This was once necessary, when Python would print any unused expression

22482

result that was not None. The method is still defined for

22483

backward compatibility.}</description>

22484

22485

<insert>ignore()</insert><dialog title="Insert ignore">ignore()</dialog><info title="Info window"></info></function>

22486

22487

</group>

22488

</group>

22489

22490

<description>High performance logging profiler, mostly written in C.

22491

New in version 2.2

22492

This module provides a nicer interface to the _hotshot C module.

22493

Hotshot is a replacement for the existing profile module. As it's

22494

written mostly in C, it should result in a much smaller performance impact

22495

than the existing profile module.

22496

</description>

22497

22498

<description>The profiler object. The argument logfile is the name of a log

22499

file to use for logged profile data. The argument lineevents

22500

specifies whether to generate events for every source line, or just on

22501

function call/return. It defaults to 0 (only log function

22502

call/return). The argument linetimings specifies whether to

22503

record timing information. It defaults to 1 (store timing

22504

information).</description>

22505

<param name="logfile" optional="0">logfile</param><param name="lineevents" optional="1" default="0">lineevents</param><param name="linetimings" optional="1" default="1">linetimings</param>

22506

<insert>Profile(logfile, [lineevents=0], [linetimings=1])</insert><dialog title="Insert Profile">Profile(%0, %1, %2)</dialog><info title="Info window"></info></function>

22507

22508

22509

<description>Profile objects have the following methods:

22510

</description>

22511

22512

<description>Add an arbitrary labelled value to the profile output.</description>

22513

<param name="key" optional="0">key</param><param name="value value" optional="0">value value</param>

22514

<insert>addinfo(key, value value)</insert><dialog title="Insert addinfo">addinfo(%0, %1)</dialog><info title="Info window"></info></function>

22515

22516

22517

<description>Close the logfile and terminate the profiler.</description>

22518

22519

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

22520

22521

22522

<description>Return the file descriptor of the profiler's log file.</description>

22523

22524

<insert>fileno()</insert><dialog title="Insert fileno">fileno()</dialog><info title="Info window"></info></function>

22525

22526

22527

<description>Profile an exec-compatible string in the script environment.

22528

The globals from the __main__ module are used as

22529

both the globals and locals for the script.</description>

22530

<param name="cmdcmd" optional="0">cmdcmd</param>

22531

<insert>run(cmdcmd)</insert><dialog title="Insert run">run(%0)</dialog><info title="Info window"></info></function>

22532

22533

22534

<description>Profile a single call of a callable.

22535

Additional positional and keyword arguments may be passed

22536

along; the result of the call is returned, and exceptions are

22537

allowed to propogate cleanly, while ensuring that profiling is

22538

disabled on the way out.</description>

22539

<param name="func" optional="0">func</param><param name="*args" optional="0">*args</param><param name="**keywords **keywords" optional="0">**keywords **keywords</param>

22540

<insert>runcall(func, *args, **keywords **keywords)</insert><dialog title="Insert runcall">runcall(%0, %1, %2)</dialog><info title="Info window"></info></function>

22541

22542

22543

<description>Evaluate an exec-compatible string in a specific environment.

22544

The string is compiled before profiling begins.</description>

22545

<param name="cmd" optional="0">cmd</param><param name="globals" optional="0">globals</param><param name="locals locals" optional="0">locals locals</param>

22546

<insert>runctx(cmd, globals, locals locals)</insert><dialog title="Insert runctx">runctx(%0, %1, %2)</dialog><info title="Info window"></info></function>

22547

22548

22549

<description>Start the profiler.</description>

22550

22551

<insert>start()</insert><dialog title="Insert start">start()</dialog><info title="Info window"></info></function>

22552

22553

22554

<description>Stop the profiler.</description>

22555

22556

22557

22558

</group>

22559

22560

<description>Statistical analysis for Hotshot

22561

New in version 2.2

22562

This module loads hotshot profiling data into the standard pstats

22563

Stats objects.

22564

</description>

22565

22566

<description>Load hotshot data from filename. Returns an instance

22567

of the pstats.Stats class.</description>

22568

<param name="filenamefilename" optional="0">filenamefilename</param>

22569

<insert>load(filenamefilename)</insert><dialog title="Insert load">load(%0)</dialog><info title="Info window"></info></function>

22570

22571

</group>

22572

22573

</group>

22574

</group>

22575

22576

<description>Measure the execution time of small code snippets.

22577

New in version 2.3

22578

</description>

22579

22580

<description>Class for timing execution speed of small code snippets.

22581

The constructor takes a statement to be timed, an additional statement

22582

used for setup, and a timer function. Both statements default to

22583

'pass'; the timer function is platform-dependent (see the

22584

module doc string). The statements may contain newlines, as long as

22585

they don't contain multi-line string literals.

22586

To measure the execution time of the first statement, use the

22587

timeit() method. The repeat() method is a

22588

convenience to call timeit() multiple times and return a list

22589

of results.</description>

22590

<param name="stmt" optional="0" default="'pass'">stmt</param><param name="setup" optional="1" default="'pass'">setup</param><param name="timer" optional="1" default="<timer function>">timer</param>

22591

<insert>Timer(stmt, [setup='pass'], [timer=<timer function>])</insert><dialog title="Insert Timer">Timer(%0, %1, %2)</dialog><info title="Info window"></info></function>

22592

22593

22594

<description>Helper to print a traceback from the timed code.

22595

Typical use:

22596

t = Timer(...) # outside the try/except

22597

try:

22598

t.timeit(...) # or t.repeat(...)

22599

except:

22600

t.print_exc()

22601

The advantage over the standard traceback is that source lines in the

22602

compiled template will be displayed.

22603

The optional file argument directs where the traceback is sent;

22604

it defaults to sys.stderr.</description>

22605

22606

<insert>print_exc(file)</insert><dialog title="Insert print_exc">print_exc(%0)</dialog><info title="Info window"></info></function>

22607

22608

22609

<description>Call timeit() a few times.

22610

This is a convenience function that calls the timeit()

22611

repeatedly, returning a list of results. The first argument specifies

22612

how many times to call timeit(). The second argument

22613

specifies the number argument for timeit().

22614

It's tempting to calculate mean and standard deviation from the result

22615

vector and report these. However, this is not very useful. In a typical

22616

case, the lowest value gives a lower bound for how fast your machine can run

22617

the given code snippet; higher values in the result vector are typically not

22618

caused by variability in Python's speed, but by other processes interfering

22619

with your timing accuracy. So the min() of the result is

22620

probably the only number you should be interested in. After that, you

22621

should look at the entire vector and apply common sense rather than

22622

statistics.

22623

</description>

22624

<param name="repeat" optional="0" default="3">repeat</param><param name="number" optional="1" default="1000000">number</param>

22625

<insert>repeat(repeat, [number=1000000])</insert><dialog title="Insert repeat">repeat(%0, %1)</dialog><info title="Info window"></info></function>

22626

22627

22628

<description>Time number executions of the main statement.

22629

This executes the setup statement once, and then

22630

returns the time it takes to execute the main statement a number of

22631

times, measured in seconds as a float. The argument is the number of

22632

times through the loop, defaulting to one million. The main

22633

statement, the setup statement and the timer function to be used are

22634

passed to the constructor.</description>

22635

<param name="number" optional="0" default="1000000">number</param>

22636

<insert>timeit(number)</insert><dialog title="Insert timeit">timeit(%0)</dialog><info title="Info window"></info></function>

22637

22638

22639

<description>When called as a program from the command line, the following form is used:

22640

python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]

22641

where the following options are understood:

22642

[-n N/number=N] how many times to execute 'statement'

22643

[-r N/repeat=N] how many times to repeat the timer (default 3)

22644

[-s S/setup=S] statement to be executed once initially (default

22645

'pass')

22646

[-t/time] use time.time()

22647

(default on all platforms but Windows)

22648

[-c/clock] use time.clock() (default on Windows)

22649

[-v/verbose] print raw timing results; repeat for more digits

22650

precision

22651

[-h/help] print a short usage message and exit

22652

A multi-line statement may be given by specifying each line as a

22653

separate statement argument; indented lines are possible by enclosing

22654

an argument in quotes and using leading spaces. Multiple

22655

-s options are treated similarly.

22656

If -n is not given, a suitable number of loops is

22657

calculated by trying successive powers of 10 until the total time is

22658

at least 0.2 seconds.

22659

The default timer function is platform dependent. On Windows,

22660

time.clock() has microsecond granularity but

22661

time.time()'s granularity is 1/60th of a second; on ,

22662

time.clock() has 1/100th of a second granularity and

22663

time.time() is much more precise. On either platform, the

22664

default timer functions measure wall clock time, not the CPU time.

22665

This means that other processes running on the same computer may

22666

interfere with the timing. The best thing to do when accurate timing

22667

is necessary is to repeat the timing a few times and use the best

22668

time. The -r option is good for this; the default of 3

22669

repetitions is probably enough in most cases. On , you can use

22670

time.clock() to measure CPU time.

22671

There is a certain baseline overhead associated with executing a

22672

pass statement. The code here doesn't try to hide it, but you

22673

should be aware of it. The baseline overhead can be measured by

22674

invoking the program without arguments.

22675

The baseline overhead differs between Python versions! Also, to

22676

fairly compare older Python versions to Python 2.3, you may want to

22677

use Python's -O option for the older versions to avoid

22678

timing SET_LINENO instructions.

22679

</description>

22680

</group>

22681

22682

</group>

22683

</group>

22684

</group>

22685

22686

22687

<description>Easy-to-use controller for Web browsers.

22688

The webbrowser module provides a very high-level interface to

22689

allow displaying Web-based documents to users. The controller objects

22690

are easy to use and are platform-independent. Under most

22691

circumstances, simply calling the open() function from this

22692

module will do the right thing.

22693

Under , graphical browsers are preferred under X11, but text-mode

22694

browsers will be used if graphical browsers are not available or an X11

22695

display isn't available. If text-mode browsers are used, the calling

22696

process will block until the user exits the browser.

22697

Under , if the environment variable BROWSER exists, it

22698

is interpreted to override the platform default list of browsers, as a

22699

colon-separated list of browsers to try in order. When the value of

22700

a list part contains the string , then it is interpreted as

22701

a literal browser command line to be used with the argument URL

22702

substituted for the ; if the part does not contain

22703

, it is simply interpreted as the name of the browser to

22704

launch.

22705

For non- platforms, or when X11 browsers are available on

22706

, the controlling process will not wait for the user to finish

22707

with the browser, but allow the browser to maintain its own window on

22708

the display.

22709

The following exception is defined:

22710

{Error}

22711

Exception raised when a browser control error occurs.

22712

The following functions are defined:

22713

</description>

22714

22715

<description>Display url using the default browser. If new is true,

22716

a new browser window is opened if possible. If autoraise is

22717

true, the window is raised if possible (note that under many window

22718

managers this will occur regardless of the setting of this variable).</description>

22719

<param name="url" optional="0">url</param><param name="new" optional="1" default="0">new</param><param name="autoraise" optional="1" default="1">autoraise</param>

22720

<insert>open(url, [new=0], [autoraise=1])</insert><dialog title="Insert open">open(%0, %1, %2)</dialog><info title="Info window"></info></function>

22721

22722

22723

<description>Open url in a new window of the default browser, if possible,

22724

otherwise, open url in the only browser window.</description>

22725

<param name="urlurl" optional="0">urlurl</param>

22726

<insert>open_new(urlurl)</insert><dialog title="Insert open_new">open_new(%0)</dialog><info title="Info window"></info></function>

22727

22728

22729

<description>Return a controller object for the browser type name. If

22730

name is empty, return a controller for a default browser

22731

appropriate to the caller's environment.</description>

22732

22733

22734

22735

22736

<description>Register the browser type name. Once a browser type is

22737

registered, the get() function can return a controller

22738

for that browser type. If instance is not provided, or is

22739

None, constructor will be called without parameters to

22740

create an instance when needed. If instance is provided,

22741

constructor will never be called, and may be None.

22742

This entry point is only useful if you plan to either set the

22743

BROWSER variable or call get with a nonempty

22744

argument matching the name of a handler you declare.</description>

22745

<param name="name" optional="0">name</param><param name="constructor" optional="0">constructor</param><param name="instance" optional="1">instance</param>

22746

<insert>register(name, constructor, [instance])</insert><dialog title="Insert register">register(%0, %1, %2)</dialog><info title="Info window"></info></function>

22747

22748

22749

<description>Browser controllers provide two methods which parallel two of the

22750

module-level convenience functions:

22751

</description>

22752

22753

<description>Display url using the browser handled by this controller. If

22754

new is true, a new browser window is opened if possible.</description>

22755

22756

22757

22758

22759

<description>Open url in a new window of the browser handled by this

22760

controller, if possible, otherwise, open url in the only

22761

browser window.</description>

22762

<param name="urlurl" optional="0">urlurl</param>

22763

<insert>open_new(urlurl)</insert><dialog title="Insert open_new">open_new(%0)</dialog><info title="Info window"></info></function>

22764

22765

</group>

22766

</group>

22767

22768

<description>Common Gateway Interface support, used to interpret

22769

forms in server-side scripts.

22770

</description>

22771

22772

<description>cgi-intro

22773

A CGI script is invoked by an HTTP server, usually to process user

22774

input submitted through an HTML <FORM> or <ISINDEX> element.

22775

Most often, CGI scripts live in the server's special cgi-bin

22776

directory. The HTTP server places all sorts of information about the

22777

request (such as the client's hostname, the requested URL, the query

22778

string, and lots of other goodies) in the script's shell environment,

22779

executes the script, and sends the script's output back to the client.

22780

The script's input is connected to the client too, and sometimes the

22781

form data is read this way; at other times the form data is passed via

22782

the ``query string'' part of the URL. This module is intended

22783

to take care of the different cases and provide a simpler interface to

22784

the Python script. It also provides a number of utilities that help

22785

in debugging scripts, and the latest addition is support for file

22786

uploads from a form (if your browser supports it --- Grail 0.3 and

22787

Netscape 2.0 do).

22788

The output of a CGI script should consist of two sections, separated

22789

by a blank line. The first section contains a number of headers,

22790

telling the client what kind of data is following. Python code to

22791

generate a minimal header section looks like this:

22792

print "Content-Type: text/html" # HTML is following

22793

print # blank line, end of headers

22794

The second section is usually HTML, which allows the client software

22795

to display nicely formatted text with header, in-line images, etc.

22796

Here's Python code that prints a simple piece of HTML:

22797

print "<TITLE>CGI script output</TITLE>"

22798

print "<H1>This is my first CGI script</H1>"

22799

print "Hello, world!"

22800

</description>

22801

</group>

22802

22803

<description>Using the cgi module

22804

Begin by writing import cgi. Do not use from cgi import

22805

* --- the module defines all sorts of names for its own use or for

22806

backward compatibility that you don't want in your namespace.

22807

When you write a new script, consider adding the line:

22808

import cgitb; cgitb.enable()

22809

This activates a special exception handler that will display detailed

22810

reports in the Web browser if any errors occur. If you'd rather not

22811

show the guts of your program to users of your script, you can have

22812

the reports saved to files instead, with a line like this:

22813

import cgitb; cgitb.enable(display=0, logdir="/tmp")

22814

It's very helpful to use this feature during script development.

22815

The reports produced by cgitb provide information that

22816

can save you a lot of time in tracking down bugs. You can always

22817

remove the cgitb line later when you have tested your script

22818

and are confident that it works correctly.

22819

To get at submitted form data,

22820

it's best to use the FieldStorage class. The other classes

22821

defined in this module are provided mostly for backward compatibility.

22822

Instantiate it exactly once, without arguments. This reads the form

22823

contents from standard input or the environment (depending on the

22824

value of various environment variables set according to the CGI

22825

standard). Since it may consume standard input, it should be

22826

instantiated only once.

22827

The FieldStorage instance can be indexed like a Python

22828

dictionary, and also supports the standard dictionary methods

22829

has_key() and keys(). The built-in len()

22830

is also supported. Form fields containing empty strings are ignored

22831

and do not appear in the dictionary; to keep such values, provide

22832

a true value for the optional keep_blank_values keyword

22833

parameter when creating the FieldStorage instance.

22834

For instance, the following code (which assumes that the Content-Type header and blank line have already been

22835

printed) checks that the fields name and addr are both

22836

set to a non-empty string:

22837

form = cgi.FieldStorage()

22838

if not (form.has_key("name") and form.has_key("addr")):

22839

print "<H1>Error</H1>"

22840

print "Please fill in the name and addr fields."

22841

return

22842

print "<p>name:", form["name"].value

22843

print "<p>addr:", form["addr"].value

22844

...further form processing here...

22845

Here the fields, accessed through form[key], are

22846

themselves instances of FieldStorage (or

22847

MiniFieldStorage, depending on the form encoding).

22848

The value attribute of the instance yields the string value

22849

of the field. The getvalue() method returns this string value

22850

directly; it also accepts an optional second argument as a default to

22851

return if the requested key is not present.

22852

If the submitted form data contains more than one field with the same

22853

name, the object retrieved by form[key] is not a

22854

FieldStorage or MiniFieldStorage

22855

instance but a list of such instances. Similarly, in this situation,

22856

form.getvalue(key) would return a list of strings.

22857

If you expect this possibility

22858

(when your HTML form contains multiple fields with the same name), use

22859

the isinstance() built-in function to determine whether you

22860

have a single instance or a list of instances. For example, this

22861

code concatenates any number of username fields, separated by

22862

commas:

22863

value = form.getvalue("username", "")

22864

if isinstance(value, list):

22865

# Multiple username fields specified

22866

usernames = ",".join(value)

22867

else:

22868

# Single or no username field specified

22869

usernames = value

22870

If a field represents an uploaded file, accessing the value via the

22871

value attribute or the getvalue() method reads the

22872

entire file in memory as a string. This may not be what you want.

22873

You can test for an uploaded file by testing either the filename

22874

attribute or the file attribute. You can then read the data at

22875

leisure from the file attribute:

22876

fileitem = form["userfile"]

22877

if fileitem.file:

22878

# It's an uploaded file; count lines

22879

linecount = 0

22880

while 1:

22881

line = fileitem.file.readline()

22882

if not line: break

22883

linecount = linecount + 1

22884

The file upload draft standard entertains the possibility of uploading

22885

multiple files from one field (using a recursive

22886

multipart/* encoding). When this occurs, the item will be

22887

a dictionary-like FieldStorage item. This can be determined

22888

by testing its type attribute, which should be

22889

multipart/form-data (or perhaps another MIME type matching

22890

multipart/*). In this case, it can be iterated over

22891

recursively just like the top-level form object.

22892

When a form is submitted in the ``old'' format (as the query string or

22893

as a single data part of type

22894

application/x-www-form-urlencoded), the items will actually

22895

be instances of the class MiniFieldStorage. In this case, the

22896

list, file, and filename attributes are

22897

always None.

22898

</description>

22899

</group>

22900

22901

<description>New in version 2.2 % XXX: Is this true ? The previous section explains how to read CGI form data using the

22902

FieldStorage class. This section describes a higher level

22903

interface which was added to this class to allow one to do it in a

22904

more readable and intuitive way. The interface doesn't make the

22905

techniques described in previous sections obsolete --- they are still

22906

useful to process file uploads efficiently, for example.

22907

The interface consists of two simple methods. Using the methods

22908

you can process form data in a generic way, without the need to worry

22909

whether only one or more values were posted under one name.

22910

In the previous section, you learned to write following code anytime

22911

you expected a user to post more than one value under one name:

22912

item = form.getvalue("item")

22913

if isinstance(item, list):

22914

# The user is requesting more than one item.

22915

else:

22916

# The user is requesting only one item.

22917

This situation is common for example when a form contains a group of

22918

multiple checkboxes with the same name:

22919

22920

22921

In most situations, however, there's only one form control with a

22922

particular name in a form and then you expect and need only one value

22923

associated with this name. So you write a script containing for

22924

example this code:

22925

user = form.getvalue("user").toupper()

22926

The problem with the code is that you should never expect that a

22927

client will provide valid input to your scripts. For example, if a

22928

curious user appends another user=foo pair to the query string,

22929

then the script would crash, because in this situation the

22930

getvalue("user") method call returns a list instead of a

22931

string. Calling the toupper() method on a list is not valid

22932

(since lists do not have a method of this name) and results in an

22933

AttributeError exception.

22934

Therefore, the appropriate way to read form data values was to always

22935

use the code which checks whether the obtained value is a single value

22936

or a list of values. That's annoying and leads to less readable

22937

scripts.

22938

A more convenient approach is to use the methods getfirst()

22939

and getlist() provided by this higher level interface.

22940

</description>

22941

22942

<description>Thin method always returns only one value associated with form field

22943

name. The method returns only the first value in case that

22944

more values were posted under such name. Please note that the order

22945

in which the values are received may vary from browser to browser

22946

and should not be counted on.Note that some recent

22947

versions of the HTML specification do state what order the

22948

field values should be supplied in, but knowing whether a

22949

request was received from a conforming browser, or even from a

22950

browser at all, is tedious and error-prone. If no such form

22951

field or value exists then the method returns the value specified by

22952

the optional parameter default. This parameter defaults to

22953

None if not specified.</description>

22954

<param name="name" optional="0">name</param><param name="default" optional="1">default</param>

22955

<insert>getfirst(name, [default])</insert><dialog title="Insert getfirst">getfirst(%0, %1)</dialog><info title="Info window"></info></function>

22956

22957

22958

<description>This method always returns a list of values associated with form

22959

field name. The method returns an empty list if no such form

22960

field or value exists for name. It returns a list consisting

22961

of one item if only one such value exists.</description>

22962

<param name="namename" optional="0">namename</param>

22963

<insert>getlist(namename)</insert><dialog title="Insert getlist">getlist(%0)</dialog><info title="Info window"></info></function>

22964

22965

</group>

22966

22967

<description>These classes, present in earlier versions of the cgi module,

22968

are still supported for backward compatibility. New applications

22969

should use the FieldStorage class.

22970

SvFormContentDict stores single value form content as

22971

dictionary; it assumes each field name occurs in the form only once.

22972

FormContentDict stores multiple value form content as a

22973

dictionary (the form items are lists of values). Useful if your form

22974

contains multiple fields with the same name.

22975

Other classes (FormContent, InterpFormContentDict) are

22976

present for backwards compatibility with really old applications only.

22977

If you still use these and would be inconvenienced when they

22978

disappeared from a next version of this module, drop me a note.

22979

</description>

22980

</group>

22981

22982

<description>Functions in cgi module

22983

These are useful if you want more control, or if you want to employ

22984

some of the algorithms implemented in this module in other

22985

circumstances.

22986

</description>

22987

22988

<description>Parse a query in the environment or from a file (the file defaults

22989

to sys.stdin). The keep_blank_values and

22990

strict_parsing parameters are passed to parse_qs()

22991

unchanged.</description>

22992

<param name="fp" optional="0">fp</param><param name="keep_blank_values" optional="1">keep_blank_values</param><param name="strict_parsing" optional="1">strict_parsing</param>

22993

<insert>parse(fp, [keep_blank_values], [strict_parsing])</insert><dialog title="Insert parse">parse(%0, %1, %2)</dialog><info title="Info window"></info></function>

22994

22995

22996

<description>Parse a query string given as a string argument (data of type application/x-www-form-urlencoded). Data are

22997

returned as a dictionary. The dictionary keys are the unique query

22998

variable names and the values are lists of values for each name.

22999

The optional argument keep_blank_values is

23000

a flag indicating whether blank values in

23001

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

23002

blank values are to be ignored and treated as if they were

23003

not included.

23004

The optional argument strict_parsing is a flag indicating what

23005

to do with parsing errors. If false (the default), errors

23006

are silently ignored. If true, errors raise a ValueError

23007

exception.

23008

Use the urllib.urlencode() function to convert

23009

such dictionaries into query strings.</description>

23010

<param name="qs" optional="0">qs</param><param name="keep_blank_values" optional="1">keep_blank_values</param><param name="strict_parsing" optional="1">strict_parsing</param>

23011

<insert>parse_qs(qs, [keep_blank_values], [strict_parsing])</insert><dialog title="Insert parse_qs">parse_qs(%0, %1, %2)</dialog><info title="Info window"></info></function>

23012

23013

23014

<description>Parse a query string given as a string argument (data of type application/x-www-form-urlencoded). Data are

23015

returned as a list of name, value pairs.

23016

The optional argument keep_blank_values is

23017

a flag indicating whether blank values in

23018

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

23019

blank values are to be ignored and treated as if they were

23020

not included.

23021

The optional argument strict_parsing is a flag indicating what

23022

to do with parsing errors. If false (the default), errors

23023

are silently ignored. If true, errors raise a ValueError

23024

exception.

23025

Use the urllib.urlencode() function to convert

23026

such lists of pairs into query strings.</description>

23027

<param name="qs" optional="0">qs</param><param name="keep_blank_values" optional="1">keep_blank_values</param><param name="strict_parsing" optional="1">strict_parsing</param>

23028

<insert>parse_qsl(qs, [keep_blank_values], [strict_parsing])</insert><dialog title="Insert parse_qsl">parse_qsl(%0, %1, %2)</dialog><info title="Info window"></info></function>

23029

23030

23031

<description>Parse input of type multipart/form-data (for file uploads). Arguments are fp for the input file and

23032

pdict for a dictionary containing other parameters in

23033

the Content-Type header.

23034

Returns a dictionary just like parse_qs() keys are the

23035

field names, each value is a list of values for that field. This is

23036

easy to use but not much good if you are expecting megabytes to be

23037

uploaded --- in that case, use the FieldStorage class instead

23038

which is much more flexible.

23039

Note that this does not parse nested multipart parts --- use

23040

FieldStorage for that.</description>

23041

<param name="fp" optional="0">fp</param><param name="pdict pdict" optional="0">pdict pdict</param>

23042

<insert>parse_multipart(fp, pdict pdict)</insert><dialog title="Insert parse_multipart">parse_multipart(%0, %1)</dialog><info title="Info window"></info></function>

23043

23044

23045

<description>Parse a MIME header (such as Content-Type) into a main

23046

value and a dictionary of parameters.</description>

23047

<param name="stringstring" optional="0">stringstring</param>

23048

<insert>parse_header(stringstring)</insert><dialog title="Insert parse_header">parse_header(%0)</dialog><info title="Info window"></info></function>

23049

23050

23051

<description>Robust test CGI script, usable as main program.

23052

Writes minimal HTTP headers and formats all information provided to

23053

the script in HTML form.</description>

23054

23055

23056

23057

23058

<description>Format the shell environment in HTML.</description>

23059

23060

<insert>print_environ()</insert><dialog title="Insert print_environ">print_environ()</dialog><info title="Info window"></info></function>

23061

23062

23063

<description>Format a form in HTML.</description>

23064

<param name="formform" optional="0">formform</param>

23065

<insert>print_form(formform)</insert><dialog title="Insert print_form">print_form(%0)</dialog><info title="Info window"></info></function>

23066

23067

23068

<description>Format the current directory in HTML.</description>

23069

23070

<insert>print_directory()</insert><dialog title="Insert print_directory">print_directory()</dialog><info title="Info window"></info></function>

23071

23072

23073

<description>Print a list of useful (used by CGI) environment variables in

23074

HTML.</description>

23075

23076

<insert>print_environ_usage()</insert><dialog title="Insert print_environ_usage">print_environ_usage()</dialog><info title="Info window"></info></function>

23077

23078

23079

<description>Convert the characters

23080

&, < and > in string s to

23081

HTML-safe sequences. Use this if you need to display text that might

23082

contain such characters in HTML. If the optional flag quote is

23083

true, the double-quote character (") is also translated;

23084

this helps for inclusion in an HTML attribute value, as in <A

23085

HREF="...">. If the value to be quoted might include single- or

23086

double-quote characters, or both, consider using the

23087

quoteattr() function in the xml.sax.saxutils

23088

module instead.</description>

23089

<param name="s" optional="0">s</param><param name="quote" optional="1">quote</param>

23090

<insert>escape(s, [quote])</insert><dialog title="Insert escape">escape(%0, %1)</dialog><info title="Info window"></info></function>

23091

23092

</group>

23093

23094

<description>There's one important rule: if you invoke an external program (via the

23095

os.system() or os.popen() functions. or others

23096

with similar functionality), make very sure you don't pass arbitrary

23097

strings received from the client to the shell. This is a well-known

23098

security hole whereby clever hackers anywhere on the Web can exploit a

23099

gullible CGI script to invoke arbitrary shell commands. Even parts of

23100

the URL or field names cannot be trusted, since the request doesn't

23101

have to come from your form!

23102

To be on the safe side, if you must pass a string gotten from a form

23103

to a shell command, you should make sure the string contains only

23104

alphanumeric characters, dashes, underscores, and periods.

23105

</description>

23106

</group>

23107

23108

<description>Read the documentation for your HTTP server and check with your local

23109

system administrator to find the directory where CGI scripts should be

23110

installed; usually this is in a directory cgi-bin in the server tree.

23111

Make sure that your script is readable and executable by ``others''; the

23112

file mode should be 0755 octal (use chmod 0755

23113

filename). Make sure that the first line of the script contains

23114

! starting in column 1 followed by the pathname of the Python

23115

interpreter, for instance:

23116

#!/usr/local/bin/python

23117

Make sure the Python interpreter exists and is executable by ``others''.

23118

Make sure that any files your script needs to read or write are

23119

readable or writable, respectively, by ``others'' --- their mode

23120

should be 0644 for readable and 0666 for writable. This

23121

is because, for security reasons, the HTTP server executes your script

23122

as user ``nobody'', without any special privileges. It can only read

23123

(write, execute) files that everybody can read (write, execute). The

23124

current directory at execution time is also different (it is usually

23125

the server's cgi-bin directory) and the set of environment variables

23126

is also different from what you get when you log in. In particular, don't

23127

count on the shell's search path for executables (PATH) or

23128

the Python module search path (PYTHONPATH) to be set to

23129

anything interesting.

23130

If you need to load modules from a directory which is not on Python's

23131

default module search path, you can change the path in your script,

23132

before importing other modules. For example:

23133

import sys

23134

sys.path.insert(0, "/usr/home/joe/lib/python")

23135

sys.path.insert(0, "/usr/local/lib/python")

23136

(This way, the directory inserted last will be searched first!)

23137

Instructions for non- systems will vary; check your HTTP server's

23138

documentation (it will usually have a section on CGI scripts).

23139

</description>

23140

</group>

23141

23142

<description>Unfortunately, a CGI script will generally not run when you try it

23143

from the command line, and a script that works perfectly from the

23144

command line may fail mysteriously when run from the server. There's

23145

one reason why you should still test your script from the command

23146

line: if it contains a syntax error, the Python interpreter won't

23147

execute it at all, and the HTTP server will most likely send a cryptic

23148

error to the client.

23149

Assuming your script has no syntax errors, yet it does not work, you

23150

have no choice but to read the next section.

23151

</description>

23152

</group>

23153

23154

<description>First of all, check for trivial installation errors --- reading the

23155

section above on installing your CGI script carefully can save you a

23156

lot of time. If you wonder whether you have understood the

23157

installation procedure correctly, try installing a copy of this module

23158

file (cgi.py) as a CGI script. When invoked as a script, the file

23159

will dump its environment and the contents of the form in HTML form.

23160

Give it the right mode etc, and send it a request. If it's installed

23161

in the standard cgi-bin directory, it should be possible to send it a

23162

request by entering a URL into your browser of the form:

23163

http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home

23164

If this gives an error of type 404, the server cannot find the script

23165

-- perhaps you need to install it in a different directory. If it

23166

gives another error, there's an installation problem that

23167

you should fix before trying to go any further. If you get a nicely

23168

formatted listing of the environment and form content (in this

23169

example, the fields should be listed as ``addr'' with value ``At Home''

23170

and ``name'' with value ``Joe Blow''), the cgi.py script has been

23171

installed correctly. If you follow the same procedure for your own

23172

script, you should now be able to debug it.

23173

The next step could be to call the cgi module's

23174

test() function from your script: replace its main code

23175

with the single statement

23176

cgi.test()

23177

This should produce the same results as those gotten from installing

23178

the cgi.py file itself.

23179

When an ordinary Python script raises an unhandled exception (for

23180

whatever reason: of a typo in a module name, a file that can't be

23181

opened, etc.), the Python interpreter prints a nice traceback and

23182

exits. While the Python interpreter will still do this when your CGI

23183

script raises an exception, most likely the traceback will end up in

23184

one of the HTTP server's log files, or be discarded altogether.

23185

Fortunately, once you have managed to get your script to execute

23186

some code, you can easily send tracebacks to the Web browser

23187

using the cgitb module. If you haven't done so already,

23188

just add the line:

23189

import cgitb; cgitb.enable()

23190

to the top of your script. Then try running it again; when a

23191

problem occurs, you should see a detailed report that will

23192

likely make apparent the cause of the crash.

23193

If you suspect that there may be a problem in importing the

23194

cgitb module, you can use an even more robust approach

23195

(which only uses built-in modules):

23196

import sys

23197

sys.stderr = sys.stdout

23198

print "Content-Type: text/plain"

23199

print

23200

...your code here...

23201

This relies on the Python interpreter to print the traceback. The

23202

content type of the output is set to plain text, which disables all

23203

HTML processing. If your script works, the raw HTML will be displayed

23204

by your client. If it raises an exception, most likely after the

23205

first two lines have been printed, a traceback will be displayed.

23206

Because no HTML interpretation is going on, the traceback will be

23207

readable.

23208

</description>

23209

</group>

23210

23211

</group>

23212

</group>

23213

23214

<description>Configurable traceback handler for CGI scripts.

23215

New in version 2.2

23216

</description>

23217

23218

<description>This function causes the cgitb module to take over the

23219

interpreter's default handling for exceptions by setting the

23220

value of sys.excepthook.

23221

(in module sys){excepthook()}

23222

The optional argument display defaults to 1 and can be set

23223

to 0 to suppress sending the traceback to the browser.

23224

If the argument logdir is present, the traceback reports are

23225

written to files. The value of logdir should be a directory

23226

where these files will be placed.

23227

The optional argument context is the number of lines of

23228

context to display around the current line of source code in the

23229

traceback; this defaults to 5.

23230

If the optional argument format is "html", the output is

23231

formatted as HTML. Any other value forces plain text output. The default

23232

value is "html".</description>

23233

<param name="display" optional="0">display</param><param name="logdir" optional="1">logdir</param><param name="context" optional="1">context</param><param name="format" optional="1">format</param>

23234

<insert>enable(display, [logdir], [context], [format])</insert><dialog title="Insert enable">enable(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

23235

23236

23237

<description>This function handles an exception using the default settings

23238

(that is, show a report in the browser, but don't log to a file).

23239

This can be used when you've caught an exception and want to

23240

report it using cgitb. The optional info argument

23241

should be a 3-tuple containing an exception type, exception

23242

value, and traceback object, exactly like the tuple returned by

23243

sys.exc_info(). If the info argument

23244

is not supplied, the current exception is obtained from

23245

sys.exc_info().</description>

23246

23247

<insert>handler(info)</insert><dialog title="Insert handler">handler(%0)</dialog><info title="Info window"></info></function>

23248

23249

</group>

23250

23251

<description>Open an arbitrary network resource by URL (requires sockets).

23252

</description>

23253

23254

<description>Open a network object denoted by a URL for reading. If the URL does

23255

not have a scheme identifier, or if it has file: as its scheme

23256

identifier, this opens a local file (without universal newlines);

23257

otherwise it opens a socket to a server somewhere on the network. If

23258

the connection cannot be made, or if the server returns an error code,

23259

the IOError exception is raised. If all went well, a

23260

file-like object is returned. This supports the following methods:

23261

read(), readline(), readlines(), fileno(),

23262

close(), info() and geturl(). It also has

23263

proper support for the iterator protocol.

23264

Except for the info() and geturl() methods,

23265

these methods have the same interface as for

23266

file objects --- see section bltin-file-objects in this

23267

manual. (It is not a built-in file object, however, so it can't be

23268

used at those few places where a true built-in file object is

23269

required.)

23270

The info() method returns an instance of the class

23271

mimetools.Message containing meta-information associated

23272

with the URL. When the method is HTTP, these headers are those

23273

returned by the server at the head of the retrieved HTML page

23274

(including Content-Length and Content-Type). When the method is FTP,

23275

a Content-Length header will be present if (as is now usual) the

23276

server passed back a file length in response to the FTP retrieval

23277

request. A Content-Type header will be present if the MIME type can

23278

be guessed. When the method is local-file, returned headers will include

23279

a Date representing the file's last-modified time, a Content-Length

23280

giving file size, and a Content-Type containing a guess at the file's

23281

type. See also the description of the

23282

mimetoolsmimetools module.

23283

The geturl() method returns the real URL of the page. In

23284

some cases, the HTTP server redirects a client to another URL. The

23285

urlopen() function handles this transparently, but in some

23286

cases the caller needs to know which URL the client was redirected

23287

to. The geturl() method can be used to get at this

23288

redirected URL.

23289

If the url uses the http: scheme identifier, the optional

23290

data argument may be given to specify a POST request

23291

(normally the request type is GET). The data argument

23292

must be in standard application/x-www-form-urlencoded format;

23293

see the urlencode() function below.

23294

The urlopen() function works transparently with proxies

23295

which do not require authentication. In a or Windows

23296

environment, set the http_proxy, ftp_proxy or

23297

gopher_proxy environment variables to a URL that identifies

23298

the proxy server before starting the Python interpreter. For example

23299

(the % is the command prompt):

23300

% http_proxy="http://www.someproxy.com:3128"

23301

% export http_proxy

23302

% python

23303

...

23304

In a Windows environment, if no proxy environment variables are set,

23305

proxy settings are obtained from the registry's Internet Settings

23306

section.

23307

In a Macintosh environment, urlopen() will retrieve proxy

23308

information from Internet</description>

23309

<param name="url" optional="0">url</param><param name="data" optional="1">data</param><param name="proxies" optional="1">proxies</param>

23310

<insert>urlopen(url, [data], [proxies])</insert><dialog title="Insert urlopen">urlopen(%0, %1, %2)</dialog><info title="Info window"></info></function>

23311

23312

23313

<description>Copy a network object denoted by a URL to a local file, if necessary.

23314

If the URL points to a local file, or a valid cached copy of the

23315

object exists, the object is not copied. Return a tuple

23316

(filename, headers) where filename is the

23317

local file name under which the object can be found, and headers

23318

is whatever the info() method of the object returned by

23319

urlopen() returned (for a remote object, possibly cached).

23320

Exceptions are the same as for urlopen().

23321

The second argument, if present, specifies the file location to copy

23322

to (if absent, the location will be a tempfile with a generated name).

23323

The third argument, if present, is a hook function that will be called

23324

once on establishment of the network connection and once after each

23325

block read thereafter. The hook will be passed three arguments; a

23326

count of blocks transferred so far, a block size in bytes, and the

23327

total size of the file. The third argument may be -1 on older

23328

FTP servers which do not return a file size in response to a retrieval

23329

request.

23330

If the url uses the http: scheme identifier, the optional

23331

data argument may be given to specify a POST request

23332

(normally the request type is GET). The data argument

23333

must in standard application/x-www-form-urlencoded format;

23334

see the urlencode() function below.</description>

23335

<param name="url" optional="0">url</param><param name="filename" optional="1">filename</param><param name="reporthook" optional="1">reporthook</param><param name="data" optional="1">data</param>

23336

<insert>urlretrieve(url, [filename], [reporthook], [data])</insert><dialog title="Insert urlretrieve">urlretrieve(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

23337

23338

23339

<description>Clear the cache that may have been built up by previous calls to

23340

urlretrieve().</description>

23341

23342

<insert>urlcleanup()</insert><dialog title="Insert urlcleanup">urlcleanup()</dialog><info title="Info window"></info></function>

23343

23344

23345

<description>Replace special characters in string using the escape.

23346

Letters, digits, and the characters _.- are never quoted.

23347

The optional safe parameter specifies additional characters

23348

that should not be quoted --- its default value is '/'.

23349

Example: quote('//') yields '/%7econnolly/'.</description>

23350

<param name="string" optional="0">string</param><param name="safe" optional="1">safe</param>

23351

<insert>quote(string, [safe])</insert><dialog title="Insert quote">quote(%0, %1)</dialog><info title="Info window"></info></function>

23352

23353

23354

<description>Like quote(), but also replaces spaces by plus signs, as

23355

required for quoting HTML form values. Plus signs in the original

23356

string are escaped unless they are included in safe. It also

23357

does not have safe default to '/'.</description>

23358

<param name="string" optional="0">string</param><param name="safe" optional="1">safe</param>

23359

<insert>quote_plus(string, [safe])</insert><dialog title="Insert quote_plus">quote_plus(%0, %1)</dialog><info title="Info window"></info></function>

23360

23361

23362

<description>Replace escapes by their single-character equivalent.

23363

Example: unquote('/%7Econnolly/') yields '//'.</description>

23364

<param name="stringstring" optional="0">stringstring</param>

23365

<insert>unquote(stringstring)</insert><dialog title="Insert unquote">unquote(%0)</dialog><info title="Info window"></info></function>

23366

23367

23368

<description>Like unquote(), but also replaces plus signs by spaces, as

23369

required for unquoting HTML form values.</description>

23370

<param name="stringstring" optional="0">stringstring</param>

23371

<insert>unquote_plus(stringstring)</insert><dialog title="Insert unquote_plus">unquote_plus(%0)</dialog><info title="Info window"></info></function>

23372

23373

23374

<description>Convert a mapping object or a sequence of two-element tuples to a

23375

``url-encoded'' string, suitable to pass to

23376

urlopen() above as the optional data argument. This

23377

is useful to pass a dictionary of form fields to a POST

23378

request. The resulting string is a series of

23379

key=value pairs separated by &

23380

characters, where both key and value are quoted using

23381

quote_plus() above. If the optional parameter doseq is

23382

present and evaluates to true, individual key=value pairs

23383

are generated for each element of the sequence.

23384

When a sequence of two-element tuples is used as the query argument,

23385

the first element of each tuple is a key and the second is a value. The

23386

order of parameters in the encoded string will match the order of parameter

23387

tuples in the sequence.

23388

The cgi module provides the functions

23389

parse_qs() and parse_qsl() which are used to

23390

parse query strings into Python data structures.</description>

23391

<param name="query" optional="0">query</param><param name="doseq" optional="1">doseq</param>

23392

<insert>urlencode(query, [doseq])</insert><dialog title="Insert urlencode">urlencode(%0, %1)</dialog><info title="Info window"></info></function>

23393

23394

23395

<description>Convert the pathname path from the local syntax for a path to

23396

the form used in the path component of a URL. This does not produce a

23397

complete URL. The return value will already be quoted using the

23398

quote() function.</description>

23399

<param name="pathpath" optional="0">pathpath</param>

23400

<insert>pathname2url(pathpath)</insert><dialog title="Insert pathname2url">pathname2url(%0)</dialog><info title="Info window"></info></function>

23401

23402

23403

<description>Convert the path component path from an encoded URL to the local

23404

syntax for a path. This does not accept a complete URL. This

23405

function uses unquote() to decode path.</description>

23406

<param name="pathpath" optional="0">pathpath</param>

23407

<insert>url2pathname(pathpath)</insert><dialog title="Insert url2pathname">url2pathname(%0)</dialog><info title="Info window"></info></function>

23408

23409

23410

<description>Base class for opening and reading URLs. Unless you need to support

23411

opening objects using schemes other than http:, ftp:,

23412

gopher: or file:, you probably want to use

23413

FancyURLopener.

23414

By default, the URLopener class sends a

23415

User-Agent header of urllib/VVV, where

23416

VVV is the urllib version number. Applications can

23417

define their own User-Agent header by subclassing

23418

URLopener or FancyURLopener and setting the instance

23419

attribute version to an appropriate string value before the

23420

open() method is called.

23421

The optional proxies parameter should be a dictionary mapping

23422

scheme names to proxy URLs, where an empty dictionary turns proxies

23423

off completely. Its default value is None, in which case

23424

environmental proxy settings will be used if present, as discussed in

23425

the definition of urlopen(), above.

23426

Additional keyword parameters, collected in x509, are used for

23427

authentication with the https: scheme. The keywords

23428

key_file and cert_file are supported; both are needed to

23429

actually retrieve a resource at an https: URL.</description>

23430

<param name="proxies" optional="0">proxies</param><param name="**x509" optional="1">**x509</param>

23431

<insert>URLopener(proxies, [**x509])</insert><dialog title="Insert URLopener">URLopener(%0, %1)</dialog><info title="Info window"></info></function>

23432

23433

23434

<description>FancyURLopener subclasses URLopener providing default

23435

handling for the following HTTP response codes: 301, 302, 303, 307 and

23436

401. For the 30x response codes listed above, the

23437

Location header is used to fetch the actual URL. For 401

23438

response codes (authentication required), basic HTTP authentication is

23439

performed. For the 30x response codes, recursion is bounded by the

23440

value of the maxtries attribute, which defaults to 10.

23441

According to the letter of 2616, 301 and 302 responses to

23442

POST requests must not be automatically redirected without

23443

confirmation by the user. In reality, browsers do allow automatic

23444

redirection of these responses, changing the POST to a GET, and

23445

urllib reproduces this behaviour.

23446

The parameters to the constructor are the same as those for

23447

URLopener.

23448

When performing basic authentication, a

23449

FancyURLopener instance calls its

23450

prompt_user_passwd() method. The default implementation asks

23451

the users for the required information on the controlling terminal. A

23452

subclass may override this method to support more appropriate behavior

23453

if needed.</description>

23454

23455

<insert>FancyURLopener(......)</insert><dialog title="Insert FancyURLopener">FancyURLopener(%0)</dialog><info title="Info window"></info></function>

23456

23457

23458

<description>URLopener and FancyURLopener objects have the

23459

following attributes.

23460

</description>

23461

23462

<description>Open fullurl using the appropriate protocol. This method sets

23463

up cache and proxy information, then calls the appropriate open method with

23464

its input arguments. If the scheme is not recognized,

23465

open_unknown() is called. The data argument

23466

has the same meaning as the data argument of urlopen().</description>

23467

<param name="fullurl" optional="0">fullurl</param><param name="data" optional="1">data</param>

23468

<insert>open(fullurl, [data])</insert><dialog title="Insert open">open(%0, %1)</dialog><info title="Info window"></info></function>

23469

23470

23471

<description>Overridable interface to open unknown URL types.</description>

23472

<param name="fullurl" optional="0">fullurl</param><param name="data" optional="1">data</param>

23473

<insert>open_unknown(fullurl, [data])</insert><dialog title="Insert open_unknown">open_unknown(%0, %1)</dialog><info title="Info window"></info></function>

23474

23475

23476

<description>Retrieves the contents of url and places it in filename. The

23477

return value is a tuple consisting of a local filename and either a

23478

mimetools.Message object containing the response headers (for remote

23479

URLs) or None (for local URLs). The caller must then open and read the

23480

contents of filename. If filename is not given and the URL

23481

refers to a local file, the input filename is returned. If the URL is

23482

non-local and filename is not given, the filename is the output of

23483

tempfile.mktemp() with a suffix that matches the suffix of the last

23484

path component of the input URL. If reporthook is given, it must be

23485

a function accepting three numeric parameters. It will be called after each

23486

chunk of data is read from the network. reporthook is ignored for

23487

local URLs.

23488

If the url uses the http: scheme identifier, the optional

23489

data argument may be given to specify a POST request

23490

(normally the request type is GET). The data argument

23491

must in standard application/x-www-form-urlencoded format;

23492

see the urlencode() function below.</description>

23493

<param name="url" optional="0">url</param><param name="filename" optional="1">filename</param><param name="reporthook" optional="1">reporthook</param><param name="data" optional="1">data</param>

23494

<insert>retrieve(url, [filename], [reporthook], [data])</insert><dialog title="Insert retrieve">retrieve(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

23495

23496

23497

<description>Return information needed to authenticate the user at the given host

23498

in the specified security realm. The return value should be a tuple,

23499

(user, password), which can be used for basic

23500

authentication.

23501

The implementation prompts for this information on the terminal; an

23502

application should override this method to use an appropriate

23503

interaction model in the local environment.</description>

23504

<param name="host" optional="0">host</param><param name="realm realm" optional="0">realm realm</param>

23505

<insert>prompt_user_passwd(host, realm realm)</insert><dialog title="Insert prompt_user_passwd">prompt_user_passwd(%0, %1)</dialog><info title="Info window"></info></function>

23506

23507

</group>

23508

23509

</group>

23510

</group>

23511

23512

<description>An extensible library for opening URLs using a variety of protocols

23513

The urllib2 module defines functions and classes which help

23514

in opening URLs (mostly HTTP) in a complex world --- basic and digest

23515

authentication, redirections and more.

23516

The urllib2 module defines the following functions:

23517

</description>

23518

23519

<description>Open the URL url, which can be either a string or a Request

23520

object (currently the code checks that it really is a Request

23521

instance, or an instance of a subclass of Request).

23522

data should be a string, which specifies additional data to

23523

send to the server. In HTTP requests, which are the only ones that

23524

support data, it should be a buffer in the format of

23525

application/x-www-form-urlencoded, for example one returned

23526

from urllib.urlencode().

23527

This function returns a file-like object with two additional methods:

23528

geturl() --- return the URL of the resource retrieved

23529

info() --- return the meta-information of the page, as

23530

a dictionary-like object

23531

Raises URLError on errors.</description>

23532

23533

<insert>urlopen(url, [data])</insert><dialog title="Insert urlopen">urlopen(%0, %1)</dialog><info title="Info window"></info></function>

23534

23535

23536

<description>Install an OpenerDirector instance as the default opener.

23537

The code does not check for a real OpenerDirector, and any

23538

class with the appropriate interface will work.</description>

23539

<param name="openeropener" optional="0">openeropener</param>

23540

<insert>install_opener(openeropener)</insert><dialog title="Insert install_opener">install_opener(%0)</dialog><info title="Info window"></info></function>

23541

23542

23543

<description>Return an OpenerDirector instance, which chains the

23544

handlers in the order given. handlers can be either instances

23545

of BaseHandler, or subclasses of BaseHandler (in

23546

which case it must be possible to call the constructor without

23547

any parameters). Instances of the following classes will be in

23548

front of the handlers, unless the handlers contain

23549

them, instances of them or subclasses of them:

23550

ProxyHandler, UnknownHandler, HTTPHandler,

23551

HTTPDefaultErrorHandler, HTTPRedirectHandler,

23552

FTPHandler, FileHandler, HTTPErrorProcessor.

23553

If the Python installation has SSL support (socket.ssl()

23554

exists), HTTPSHandler will also be added.

23555

Beginning in Python 2.3, a BaseHandler subclass may also

23556

change its handler_order member variable to modify its

23557

position in the handlers list. Besides ProxyHandler, which has

23558

handler_order of 100, all handlers currently have it

23559

set to 500.</description>

23560

<param name="handler" optional="0">handler</param><param name="moreargs" optional="1">moreargs</param>

23561

<insert>build_opener(handler, [moreargs])</insert><dialog title="Insert build_opener">build_opener(%0, %1)</dialog><info title="Info window"></info></function>

23562

23563

23564

<description>This class is an abstraction of a URL request.

23565

url should be a string which is a valid URL. For a description

23566

of data see the add_data() description.

23567

headers should be a dictionary, and will be treated as if

23568

add_header() was called with each key and value as arguments.</description>

23569

<param name="url" optional="0">url</param><param name="data" optional="1">data</param><param name="headers" optional="1">headers</param>

23570

<insert>Request(url, [data], [headers])</insert><dialog title="Insert Request">Request(%0, %1, %2)</dialog><info title="Info window"></info></function>

23571

23572

23573

<description>The OpenerDirector class opens URLs via BaseHandlers

23574

chained together. It manages the chaining of handlers, and recovery

23575

from errors.</description>

23576

23577

<insert>OpenerDirector()</insert><dialog title="Insert OpenerDirector">OpenerDirector()</dialog><info title="Info window"></info></function>

23578

23579

23580

<description>This is the base class for all registered handlers --- and handles only

23581

the simple mechanics of registration.</description>

23582

23583

<insert>BaseHandler()</insert><dialog title="Insert BaseHandler">BaseHandler()</dialog><info title="Info window"></info></function>

23584

23585

23586

<description>A class which defines a default handler for HTTP error responses; all

23587

responses are turned into HTTPError exceptions.</description>

23588

23589

<insert>HTTPDefaultErrorHandler()</insert><dialog title="Insert HTTPDefaultErrorHandler">HTTPDefaultErrorHandler()</dialog><info title="Info window"></info></function>

23590

23591

23592

<description>A class to handle redirections.</description>

23593

23594

<insert>HTTPRedirectHandler()</insert><dialog title="Insert HTTPRedirectHandler">HTTPRedirectHandler()</dialog><info title="Info window"></info></function>

23595

23596

23597

<description>Cause requests to go through a proxy.

23598

If proxies is given, it must be a dictionary mapping

23599

protocol names to URLs of proxies.

23600

The default is to read the list of proxies from the environment

23601

variables protocol_proxy.</description>

23602

<param name="proxies" optional="0">proxies</param>

23603

<insert>ProxyHandler(proxies)</insert><dialog title="Insert ProxyHandler">ProxyHandler(%0)</dialog><info title="Info window"></info></function>

23604

23605

23606

<description>Keep a database of (realm, uri) -> (user, password)

23607

mappings.</description>

23608

23609

<insert>HTTPPasswordMgr()</insert><dialog title="Insert HTTPPasswordMgr">HTTPPasswordMgr()</dialog><info title="Info window"></info></function>

23610

23611

23612

<description>Keep a database of (realm, uri) -> (user, password) mappings.

23613

A realm of None is considered a catch-all realm, which is searched

23614

if no other realm fits.</description>

23615

23616

<insert>HTTPPasswordMgrWithDefaultRealm()</insert><dialog title="Insert HTTPPasswordMgrWithDefaultRealm">HTTPPasswordMgrWithDefaultRealm()</dialog><info title="Info window"></info></function>

23617

23618

23619

<description>This is a mixin class that helps with HTTP authentication, both

23620

to the remote host and to a proxy.

23621

password_mgr, if given, should be something that is compatible

23622

with HTTPPasswordMgr; refer to section~http-password-mgr

23623

for information on the interface that must be supported.</description>

23624

<param name="password_mgr" optional="0">password_mgr</param>

23625

<insert>AbstractBasicAuthHandler(password_mgr)</insert><dialog title="Insert AbstractBasicAuthHandler">AbstractBasicAuthHandler(%0)</dialog><info title="Info window"></info></function>

23626

23627

23628

<description>Handle authentication with the remote host.

23629

password_mgr, if given, should be something that is compatible

23630

with HTTPPasswordMgr; refer to section~http-password-mgr

23631

for information on the interface that must be supported.</description>

23632

<param name="password_mgr" optional="0">password_mgr</param>

23633

<insert>HTTPBasicAuthHandler(password_mgr)</insert><dialog title="Insert HTTPBasicAuthHandler">HTTPBasicAuthHandler(%0)</dialog><info title="Info window"></info></function>

23634

23635

23636

<description>Handle authentication with the proxy.

23637

password_mgr, if given, should be something that is compatible

23638

with HTTPPasswordMgr; refer to section~http-password-mgr

23639

for information on the interface that must be supported.</description>

23640

<param name="password_mgr" optional="0">password_mgr</param>

23641

<insert>ProxyBasicAuthHandler(password_mgr)</insert><dialog title="Insert ProxyBasicAuthHandler">ProxyBasicAuthHandler(%0)</dialog><info title="Info window"></info></function>

23642

23643

23644

<description>This is a mixin class that helps with HTTP authentication, both

23645

to the remote host and to a proxy.

23646

password_mgr, if given, should be something that is compatible

23647

with HTTPPasswordMgr; refer to section~http-password-mgr

23648

for information on the interface that must be supported.</description>

23649

<param name="password_mgr" optional="0">password_mgr</param>

23650

<insert>AbstractDigestAuthHandler(password_mgr)</insert><dialog title="Insert AbstractDigestAuthHandler">AbstractDigestAuthHandler(%0)</dialog><info title="Info window"></info></function>

23651

23652

23653

<description>Handle authentication with the remote host.

23654

password_mgr, if given, should be something that is compatible

23655

with HTTPPasswordMgr; refer to section~http-password-mgr

23656

for information on the interface that must be supported.</description>

23657

<param name="password_mgr" optional="0">password_mgr</param>

23658

<insert>HTTPDigestAuthHandler(password_mgr)</insert><dialog title="Insert HTTPDigestAuthHandler">HTTPDigestAuthHandler(%0)</dialog><info title="Info window"></info></function>

23659

23660

23661

<description>Handle authentication with the proxy.

23662

password_mgr, if given, should be something that is compatible

23663

with HTTPPasswordMgr; refer to section~http-password-mgr

23664

for information on the interface that must be supported.</description>

23665

<param name="password_mgr" optional="0">password_mgr</param>

23666

<insert>ProxyDigestAuthHandler(password_mgr)</insert><dialog title="Insert ProxyDigestAuthHandler">ProxyDigestAuthHandler(%0)</dialog><info title="Info window"></info></function>

23667

23668

23669

<description>A class to handle opening of HTTP URLs.</description>

23670

23671

<insert>HTTPHandler()</insert><dialog title="Insert HTTPHandler">HTTPHandler()</dialog><info title="Info window"></info></function>

23672

23673

23674

<description>A class to handle opening of HTTPS URLs.</description>

23675

23676

<insert>HTTPSHandler()</insert><dialog title="Insert HTTPSHandler">HTTPSHandler()</dialog><info title="Info window"></info></function>

23677

23678

23679

<description>Open local files.</description>

23680

23681

<insert>FileHandler()</insert><dialog title="Insert FileHandler">FileHandler()</dialog><info title="Info window"></info></function>

23682

23683

23684

23685

23686

<insert>FTPHandler()</insert><dialog title="Insert FTPHandler">FTPHandler()</dialog><info title="Info window"></info></function>

23687

23688

23689

<description>Open FTP URLs, keeping a cache of open FTP connections to minimize

23690

delays.</description>

23691

23692

<insert>CacheFTPHandler()</insert><dialog title="Insert CacheFTPHandler">CacheFTPHandler()</dialog><info title="Info window"></info></function>

23693

23694

23695

<description>Open gopher URLs.</description>

23696

23697

<insert>GopherHandler()</insert><dialog title="Insert GopherHandler">GopherHandler()</dialog><info title="Info window"></info></function>

23698

23699

23700

<description>A catch-all class to handle unknown URLs.</description>

23701

23702

<insert>UnknownHandler()</insert><dialog title="Insert UnknownHandler">UnknownHandler()</dialog><info title="Info window"></info></function>

23703

23704

23705

<description>The following methods describe all of Request's public interface,

23706

and so all must be overridden in subclasses.

23707

</description>

23708

23709

<description>Set the Request data to data. This is ignored

23710

by all handlers except HTTP handlers --- and there it should be an

23711

application/x-www-form-encoded buffer, and will change the

23712

request to be POST rather than GET.</description>

23713

<param name="datadata" optional="0">datadata</param>

23714

<insert>add_data(datadata)</insert><dialog title="Insert add_data">add_data(%0)</dialog><info title="Info window"></info></function>

23715

23716

23717

<description>Return a string indicating the HTTP request method. This is only

23718

meaningful for HTTP requests, and currently always takes one of the

23719

values ("GET", "POST").</description>

23720

23721

<insert>get_method()</insert><dialog title="Insert get_method">get_method()</dialog><info title="Info window"></info></function>

23722

23723

23724

<description>Return whether the instance has a non-None data.</description>

23725

23726

23727

23728

23729

<description>Return the instance's data.</description>

23730

23731

23732

23733

23734

<description>Add another header to the request. Headers are currently ignored by

23735

all handlers except HTTP handlers, where they are added to the list

23736

of headers sent to the server. Note that there cannot be more than

23737

one header with the same name, and later calls will overwrite

23738

previous calls in case the key collides. Currently, this is

23739

no loss of HTTP functionality, since all headers which have meaning

23740

when used more than once have a (header-specific) way of gaining the

23741

same functionality using only one header.</description>

23742

23743

<insert>add_header(key, val val)</insert><dialog title="Insert add_header">add_header(%0, %1)</dialog><info title="Info window"></info></function>

23744

23745

23746

<description>Add a header that will not be added to a redirected request.</description>

23747

<param name="key" optional="0">key</param><param name="header header" optional="0">header header</param>

23748

<insert>add_unredirected_header(key, header header)</insert><dialog title="Insert add_unredirected_header">add_unredirected_header(%0, %1)</dialog><info title="Info window"></info></function>

23749

23750

23751

<description>Return whether the instance has the named header (checks both regular

23752

and unredirected).</description>

23753

<param name="headerheader" optional="0">headerheader</param>

23754

<insert>has_header(headerheader)</insert><dialog title="Insert has_header">has_header(%0)</dialog><info title="Info window"></info></function>

23755

23756

23757

<description>Return the URL given in the constructor.</description>

23758

23759

23760

23761

23762

<description>Return the type of the URL --- also known as the scheme.</description>

23763

23764

23765

23766

23767

<description>Return the host to which a connection will be made.</description>

23768

23769

23770

23771

23772

<description>Return the selector --- the part of the URL that is sent to

23773

the server.</description>

23774

23775

<insert>get_selector()</insert><dialog title="Insert get_selector">get_selector()</dialog><info title="Info window"></info></function>

23776

23777

23778

<description>Prepare the request by connecting to a proxy server. The host

23779

and type will replace those of the instance, and the instance's

23780

selector will be the original URL given in the constructor.</description>

23781

23782

<insert>set_proxy(host, type type)</insert><dialog title="Insert set_proxy">set_proxy(%0, %1)</dialog><info title="Info window"></info></function>

23783

23784

</group>

23785

23786

<description>OpenerDirector instances have the following methods:

23787

</description>

23788

23789

<description>handler should be an instance of BaseHandler. The

23790

following methods are searched, and added to the possible chains.

23791

protocol_open() ---

23792

signal that the handler knows how to open protocol URLs.

23793

protocol_error_type() ---

23794

signal that the handler knows how to handle type errors from

23795

protocol.

23796

protocol_request() ---

23797

signal that the handler knows how to pre-process protocol

23798

requests.

23799

protocol_response() ---

23800

signal that the handler knows how to post-process protocol

23801

responses.

23802

</description>

23803

<param name="handlerhandler" optional="0">handlerhandler</param>

23804

<insert>add_handler(handlerhandler)</insert><dialog title="Insert add_handler">add_handler(%0)</dialog><info title="Info window"></info></function>

23805

23806

23807

<description>Explicitly break cycles, and delete all the handlers.

23808

Because the OpenerDirector needs to know the registered handlers,

23809

and a handler needs to know who the OpenerDirector who called

23810

it is, there is a reference cycle. Even though recent versions of Python

23811

have cycle-collection, it is sometimes preferable to explicitly break

23812

the cycles.</description>

23813

23814

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

23815

23816

23817

<description>Open the given url (which can be a request object or a string),

23818

optionally passing the given data.

23819

Arguments, return values and exceptions raised are the same as those

23820

of urlopen() (which simply calls the open() method

23821

on the default installed OpenerDirector).</description>

23822

23823

23824

23825

23826

<description>Handle an error in a given protocol. This will call the registered

23827

error handlers for the given protocol with the given arguments (which

23828

are protocol specific). The HTTP protocol is a special case which

23829

uses the HTTP response code to determine the specific error handler;

23830

refer to the http_error_*() methods of the handler classes.

23831

Return values and exceptions raised are the same as those

23832

of urlopen().</description>

23833

<param name="proto" optional="0">proto</param><param name="arg" optional="1">arg</param><param name="moreargs" optional="1">moreargs</param>

23834

<insert>error(proto, [arg], [moreargs])</insert><dialog title="Insert error">error(%0, %1, %2)</dialog><info title="Info window"></info></function>

23835

23836

</group>

23837

23838

<description>BaseHandler objects provide a couple of methods that are

23839

directly useful, and others that are meant to be used by derived

23840

classes. These are intended for direct use:

23841

</description>

23842

23843

<description>Add a director as parent.</description>

23844

<param name="directordirector" optional="0">directordirector</param>

23845

<insert>add_parent(directordirector)</insert><dialog title="Insert add_parent">add_parent(%0)</dialog><info title="Info window"></info></function>

23846

23847

23848

<description>Remove any parents.</description>

23849

23850

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

23851

23852

23853

<description>This method is not defined in BaseHandler, but

23854

subclasses should define it if they want to catch all URLs.

23855

This method, if implemented, will be called by the parent

23856

OpenerDirector. It should return a file-like object as

23857

described in the return value of the open() of

23858

OpenerDirector, or None. It should raise

23859

URLError, unless a truly exceptional thing happens (for

23860

example, MemoryError should not be mapped to

23861

URLError).

23862

This method will be called before any protocol-specific open method.</description>

23863

<param name="reqreq" optional="0">reqreq</param>

23864

<insert>default_open(reqreq)</insert><dialog title="Insert default_open">default_open(%0)</dialog><info title="Info window"></info></function>

23865

23866

23867

<description>This method is not defined in BaseHandler, but

23868

subclasses should define it if they want to catch all URLs with no

23869

specific registered handler to open it.

23870

This method, if implemented, will be called by the parent OpenerDirector. Return values should be the same as for default_open().</description>

23871

<param name="reqreq" optional="0">reqreq</param>

23872

<insert>unknown_open(reqreq)</insert><dialog title="Insert unknown_open">unknown_open(%0)</dialog><info title="Info window"></info></function>

23873

23874

23875

<description>This method is not defined in BaseHandler, but

23876

subclasses should override it if they intend to provide a catch-all

23877

for otherwise unhandled HTTP errors. It will be called automatically

23878

by the OpenerDirector getting the error, and should not

23879

normally be called in other circumstances.

23880

req will be a Request object, fp will be a

23881

file-like object with the HTTP error body, code will be the

23882

three-digit code of the error, msg will be the user-visible

23883

explanation of the code and hdrs will be a mapping object with

23884

the headers of the error.

23885

Return values and exceptions raised should be the same as those

23886

of urlopen().</description>

23887

23888

<insert>http_error_default(req, fp, code, msg, hdrs hdrs)</insert><dialog title="Insert http_error_default">http_error_default(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

23889

23890

23891

</group>

23892

23893

<description>Some HTTP redirections require action from this module's client

23894

code. If this is the case, HTTPError is raised. See

23895

2616 for details of the precise meanings of the various

23896

redirection codes.

23897

</description>

23898

23899

<description>Return a Request or None in response to a redirect.

23900

This is called by the default implementations of the

23901

http_error_30*() methods when a redirection is received

23902

from the server. If a redirection should take place, return a new

23903

Request to allow http_error_30*() to perform the

23904

redirect. Otherwise, raise HTTPError if no other

23905

Handler should try to handle this URL, or return None

23906

if you can't but another Handler might.

23907

The default implementation of this method does not strictly

23908

follow 2616, which says that 301 and 302 responses to POST

23909

requests must not be automatically redirected without confirmation by

23910

the user. In reality, browsers do allow automatic redirection of

23911

these responses, changing the POST to a GET, and the default

23912

implementation reproduces this behavior.

23913

</description>

23914

23915

<insert>redirect_request(req, fp, code, msg, hdrs hdrs)</insert><dialog title="Insert redirect_request">redirect_request(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

23916

23917

23918

<description>Redirect to the Location: URL. This method is called by

23919

the parent OpenerDirector when getting an HTTP

23920

`moved permanently' response.</description>

23921

23922

<insert>http_error_301(req, fp, code, msg, hdrs hdrs)</insert><dialog title="Insert http_error_301">http_error_301(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

23923

23924

23925

<description>The same as http_error_301(), but called for the

23926

`found' response.</description>

23927

23928

<insert>http_error_302(req, fp, code, msg, hdrs hdrs)</insert><dialog title="Insert http_error_302">http_error_302(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

23929

23930

23931

<description>The same as http_error_301(), but called for the

23932

`see other' response.</description>

23933

23934

<insert>http_error_303(req, fp, code, msg, hdrs hdrs)</insert><dialog title="Insert http_error_303">http_error_303(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

23935

23936

23937

<description>The same as http_error_301(), but called for the

23938

`temporary redirect' response.</description>

23939

23940

<insert>http_error_307(req, fp, code, msg, hdrs hdrs)</insert><dialog title="Insert http_error_307">http_error_307(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

23941

23942

</group>

23943

23944

<description>[ProxyHandler]{protocol_open}{request}

23945

The ProxyHandler will have a method

23946

protocol_open() for every protocol which has a

23947

proxy in the proxies dictionary given in the constructor. The

23948

method will modify requests to go through the proxy, by calling

23949

request.set_proxy(), and call the next handler in the chain to

23950

actually execute the protocol.

23951

</description>

23952

</group>

23953

23954

<description>These methods are available on HTTPPasswordMgr and

23955

HTTPPasswordMgrWithDefaultRealm objects.

23956

</description>

23957

23958

<description>uri can be either a single URI, or a sequene of URIs. realm,

23959

user and passwd must be strings. This causes

23960

(user, passwd) to be used as authentication tokens

23961

when authentication for realm and a super-URI of any of the

23962

given URIs is given.</description>

23963

<param name="realm" optional="0">realm</param><param name="uri" optional="0">uri</param><param name="user" optional="0">user</param><param name="passwd passwd" optional="0">passwd passwd</param>

23964

<insert>add_password(realm, uri, user, passwd passwd)</insert><dialog title="Insert add_password">add_password(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

23965

23966

23967

<description>Get user/password for given realm and URI, if any. This method will

23968

return (None, None) if there is no matching user/password.

23969

For HTTPPasswordMgrWithDefaultRealm objects, the realm

23970

None will be searched if the given realm has no matching

23971

user/password.</description>

23972

<param name="realm" optional="0">realm</param><param name="authuri authuri" optional="0">authuri authuri</param>

23973

<insert>find_user_password(realm, authuri authuri)</insert><dialog title="Insert find_user_password">find_user_password(%0, %1)</dialog><info title="Info window"></info></function>

23974

23975

</group>

23976

23977

23978

<description>Handle an authentication request by getting a user/password pair, and

23979

re-trying the request. authreq should be the name of the header

23980

where the information about the realm is included in the request,

23981

host is the host to authenticate to, req should be the

23982

(failed) Request object, and headers should be the error

23983

headers.</description>

23984

<param name="authreq" optional="0">authreq</param><param name="host" optional="0">host</param><param name="req" optional="0">req</param><param name="headers headers" optional="0">headers headers</param>

23985

<insert>handle_authentication_request(authreq, host, req, headers headers)</insert><dialog title="Insert handle_authentication_request">handle_authentication_request(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

23986

23987

</group>

23988

23989

23990

<description>Retry the request with authentication information, if available.</description>

23991

23992

<insert>http_error_401(req, fp, code, msg, hdrs hdrs)</insert><dialog title="Insert http_error_401">http_error_401(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

23993

23994

</group>

23995

23996

23997

<description>Retry the request with authentication information, if available.</description>

23998

23999

<insert>http_error_407(req, fp, code, msg, hdrs hdrs)</insert><dialog title="Insert http_error_407">http_error_407(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

24000

24001

</group>

24002

24003

24004

<description>authreq should be the name of the header where the information about

24005

the realm is included in the request, host should be the host to

24006

authenticate to, req should be the (failed) Request

24007

object, and headers should be the error headers.</description>

24008

<param name="authreq" optional="0">authreq</param><param name="host" optional="0">host</param><param name="req" optional="0">req</param><param name="headers headers" optional="0">headers headers</param>

24009

<insert>handle_authentication_request(authreq, host, req, headers headers)</insert><dialog title="Insert handle_authentication_request">handle_authentication_request(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24010

24011

</group>

24012

24013

24014

<description>Retry the request with authentication information, if available.</description>

24015

24016

<insert>http_error_401(req, fp, code, msg, hdrs hdrs)</insert><dialog title="Insert http_error_401">http_error_401(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

24017

24018

</group>

24019

24020

24021

<description>Retry the request with authentication information, if available.</description>

24022

24023

<insert>http_error_407(req, fp, code, msg, hdrs hdrs)</insert><dialog title="Insert http_error_407">http_error_407(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

24024

24025

</group>

24026

24027

24028

<description>Send an HTTP request, which can be either GET or POST, depending on

24029

req.has_data().</description>

24030

<param name="reqreq" optional="0">reqreq</param>

24031

<insert>http_open(reqreq)</insert><dialog title="Insert http_open">http_open(%0)</dialog><info title="Info window"></info></function>

24032

24033

</group>

24034

24035

24036

<description>Send an HTTPS request, which can be either GET or POST, depending on

24037

req.has_data().</description>

24038

<param name="reqreq" optional="0">reqreq</param>

24039

<insert>https_open(reqreq)</insert><dialog title="Insert https_open">https_open(%0)</dialog><info title="Info window"></info></function>

24040

24041

</group>

24042

24043

24044

<description>Open the file locally, if there is no host name, or

24045

the host name is 'localhost'. Change the

24046

protocol to ftp otherwise, and retry opening

24047

it using parent.</description>

24048

<param name="reqreq" optional="0">reqreq</param>

24049

<insert>file_open(reqreq)</insert><dialog title="Insert file_open">file_open(%0)</dialog><info title="Info window"></info></function>

24050

24051

</group>

24052

24053

24054

<description>Open the FTP file indicated by req.

24055

The login is always done with empty username and password.</description>

24056

<param name="reqreq" optional="0">reqreq</param>

24057

<insert>ftp_open(reqreq)</insert><dialog title="Insert ftp_open">ftp_open(%0)</dialog><info title="Info window"></info></function>

24058

24059

</group>

24060

24061

<description>CacheFTPHandler objects are FTPHandler objects with

24062

the following additional methods:

24063

</description>

24064

24065

<description>Set timeout of connections to t seconds.</description>

24066

24067

<insert>setTimeout(tt)</insert><dialog title="Insert setTimeout">setTimeout(%0)</dialog><info title="Info window"></info></function>

24068

24069

24070

<description>Set maximum number of cached connections to m.</description>

24071

24072

<insert>setMaxConns(mm)</insert><dialog title="Insert setMaxConns">setMaxConns(%0)</dialog><info title="Info window"></info></function>

24073

24074

</group>

24075

24076

24077

<description>Open the gopher resource indicated by req.</description>

24078

<param name="reqreq" optional="0">reqreq</param>

24079

<insert>gopher_open(reqreq)</insert><dialog title="Insert gopher_open">gopher_open(%0)</dialog><info title="Info window"></info></function>

24080

24081

</group>

24082

24083

24084

<description>Raise a URLError exception.</description>

24085

24086

<insert>unknown_open()</insert><dialog title="Insert unknown_open">unknown_open()</dialog><info title="Info window"></info></function>

24087

24088

</group>

24089

24090

24091

<description>Process HTTP error responses.

24092

For 200 error codes, the response object is returned immediately.

24093

For non-200 error codes, this simply passes the job on to the

24094

protocol_error_code() handler methods, via

24095

OpenerDirector.error(). Eventually,

24096

urllib2.HTTPDefaultErrorHandler will raise an

24097

HTTPError if no other handler handles the error.</description>

24098

24099

<insert>unknown_open()</insert><dialog title="Insert unknown_open">unknown_open()</dialog><info title="Info window"></info></function>

24100

24101

</group>

24102

24103

</group>

24104

</group>

24105

24106

<description>HTTP and HTTPS protocol client (requires sockets).

24107

</description>

24108

24109

<description>An HTTPConnection instance represents one transaction with an HTTP

24110

server. It should be instantiated passing it a host and optional port number.

24111

If no port number is passed, the port is extracted from the host string if it

24112

has the form host:port, else the default HTTP port (80) is

24113

used. For example, the following calls all create instances that connect to

24114

the server at the same host and port:

24115

>>> h1 = httplib.HTTPConnection('www.cwi.nl')

24116

>>> h2 = httplib.HTTPConnection('www.cwi.nl:80')

24117

>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)

24118

New in version 2.0</description>

24119

24120

<insert>HTTPConnection(host, [port])</insert><dialog title="Insert HTTPConnection">HTTPConnection(%0, %1)</dialog><info title="Info window"></info></function>

24121

24122

24123

<description>A subclass of HTTPConnection that uses SSL for communication with

24124

secure servers. Default port is 443.

24125

key_file is

24126

the name of a PEM formatted file that contains your private

24127

key. cert_file is a PEM formatted certificate chain file.

24128

This does not do any certificate verification!

24129

New in version 2.0</description>

24130

24131

<insert>HTTPSConnection(host, [port], [key_file], [cert_file])</insert><dialog title="Insert HTTPSConnection">HTTPSConnection(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24132

24133

24134

<description>Class whose instances are returned upon successful connection. Not

24135

instantiated directly by user.

24136

New in version 2.0</description>

24137

<param name="sock" optional="0">sock</param><param name="debuglevel" optional="1" default="0">debuglevel</param><param name="strict" optional="1" default="0">strict</param>

24138

<insert>HTTPResponse(sock, [debuglevel=0], [strict=0])</insert><dialog title="Insert HTTPResponse">HTTPResponse(%0, %1, %2)</dialog><info title="Info window"></info></function>

24139

24140

24141

<description>HTTPConnection instances have the following methods:

24142

</description>

24143

24144

<description>This will send a request to the server using the HTTP request method

24145

method and the selector url. If the body argument is

24146

present, it should be a string of data to send after the headers are finished.

24147

The header Content-Length is automatically set to the correct value.

24148

The headers argument should be a mapping of extra HTTP headers to send

24149

with the request.</description>

24150

<param name="method" optional="0">method</param><param name="url" optional="0">url</param><param name="body" optional="1">body</param><param name="headers" optional="1">headers</param>

24151

<insert>request(method, url, [body], [headers])</insert><dialog title="Insert request">request(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24152

24153

24154

<description>Should be called after a request is sent to get the response from the server.

24155

Returns an HTTPResponse instance.</description>

24156

24157

<insert>getresponse()</insert><dialog title="Insert getresponse">getresponse()</dialog><info title="Info window"></info></function>

24158

24159

24160

<description>Set the debugging level (the amount of debugging output printed).

24161

The default debug level is 0, meaning no debugging output is

24162

printed.</description>

24163

<param name="levellevel" optional="0">levellevel</param>

24164

<insert>set_debuglevel(levellevel)</insert><dialog title="Insert set_debuglevel">set_debuglevel(%0)</dialog><info title="Info window"></info></function>

24165

24166

24167

<description>Connect to the server specified when the object was created.</description>

24168

24169

<insert>connect()</insert><dialog title="Insert connect">connect()</dialog><info title="Info window"></info></function>

24170

24171

24172

<description>Close the connection to the server.</description>

24173

24174

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

24175

24176

24177

<description>Send data to the server. This should be used directly only after the

24178

endheaders() method has been called and before

24179

getreply() has been called.</description>

24180

<param name="datadata" optional="0">datadata</param>

24181

<insert>send(datadata)</insert><dialog title="Insert send">send(%0)</dialog><info title="Info window"></info></function>

24182

24183

24184

<description>This should be the first call after the connection to the server has

24185

been made. It sends a line to the server consisting of the

24186

request string, the selector string, and the HTTP version

24187

(HTTP/1.1). To disable automatic sending of Host: or

24188

Accept-Encoding: headers (for example to accept additional

24189

content encodings), specify skip_host or skip_accept_encoding

24190

with non-False values.

24191

Changed in version 2.4: skip_accept_encoding argument added</description>

24192

<param name="request" optional="0">request</param><param name="selector" optional="0">selector</param><param name="skip_host" optional="1">skip_host</param><param name="skip_accept_encoding" optional="1">skip_accept_encoding</param>

24193

<insert>putrequest(request, selector, [skip_host], [skip_accept_encoding])</insert><dialog title="Insert putrequest">putrequest(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24194

24195

24196

<description>Send an 822-style header to the server. It sends a line to the

24197

server consisting of the header, a colon and a space, and the first

24198

argument. If more arguments are given, continuation lines are sent,

24199

each consisting of a tab and an argument.</description>

24200

<param name="header" optional="0">header</param><param name="argument" optional="0">argument</param><param name="..." optional="1">...</param>

24201

<insert>putheader(header, argument, [...])</insert><dialog title="Insert putheader">putheader(%0, %1, %2)</dialog><info title="Info window"></info></function>

24202

24203

24204

<description>Send a blank line to the server, signalling the end of the headers.</description>

24205

24206

<insert>endheaders()</insert><dialog title="Insert endheaders">endheaders()</dialog><info title="Info window"></info></function>

24207

24208

</group>

24209

24210

<description>HTTPResponse instances have the following methods and attributes:

24211

</description>

24212

24213

<description>Reads and returns the response body, or up to the next amt bytes.</description>

24214

24215

24216

24217

24218

<description>Get the contents of the header name, or default if there is no

24219

matching header.</description>

24220

<param name="name" optional="0">name</param><param name="default" optional="1">default</param>

24221

<insert>getheader(name, [default])</insert><dialog title="Insert getheader">getheader(%0, %1)</dialog><info title="Info window"></info></function>

24222

24223

</group>

24224

24225

</group>

24226

</group>

24227

24228

<description>FTP protocol client (requires sockets).

24229

</description>

24230

24231

<description>Return a new instance of the FTP class. When

24232

host is given, the method call connect(host) is

24233

made. When user is given, additionally the method call

24234

login(user, passwd, acct) is made (where

24235

passwd and acct default to the empty string when not given).</description>

24236

<param name="host" optional="0">host</param><param name="user" optional="1">user</param><param name="passwd" optional="1">passwd</param><param name="acct" optional="1">acct</param>

24237

<insert>FTP(host, [user], [passwd], [acct])</insert><dialog title="Insert FTP">FTP(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24238

24239

24240

<description>Several methods are available in two flavors: one for handling text

24241

files and another for binary files. These are named for the command

24242

which is used followed by lines for the text version or

24243

binary for the binary version.

24244

FTP instances have the following methods:

24245

</description>

24246

24247

<description>Set the instance's debugging level. This controls the amount of

24248

debugging output printed. The default, 0, produces no

24249

debugging output. A value of 1 produces a moderate amount of

24250

debugging output, generally a single line per request. A value of

24251

2 or higher produces the maximum amount of debugging output,

24252

logging each line sent and received on the control connection.</description>

24253

<param name="levellevel" optional="0">levellevel</param>

24254

<insert>set_debuglevel(levellevel)</insert><dialog title="Insert set_debuglevel">set_debuglevel(%0)</dialog><info title="Info window"></info></function>

24255

24256

24257

<description>Connect to the given host and port. The default port number is 21, as

24258

specified by the FTP protocol specification. It is rarely needed to

24259

specify a different port number. This function should be called only

24260

once for each instance; it should not be called at all if a host was

24261

given when the instance was created. All other methods can only be

24262

used after a connection has been made.</description>

24263

24264

<insert>connect(host, [port])</insert><dialog title="Insert connect">connect(%0, %1)</dialog><info title="Info window"></info></function>

24265

24266

24267

<description>Return the welcome message sent by the server in reply to the initial

24268

connection. (This message sometimes contains disclaimers or help

24269

information that may be relevant to the user.)</description>

24270

24271

<insert>getwelcome()</insert><dialog title="Insert getwelcome">getwelcome()</dialog><info title="Info window"></info></function>

24272

24273

24274

<description>Log in as the given user. The passwd and acct

24275

parameters are optional and default to the empty string. If no

24276

user is specified, it defaults to 'anonymous'. If

24277

user is 'anonymous', the default passwd is

24278

'anonymous@'. This function should be called only

24279

once for each instance, after a connection has been established; it

24280

should not be called at all if a host and user were given when the

24281

instance was created. Most FTP commands are only allowed after the

24282

client has logged in.</description>

24283

<param name="user" optional="0">user</param><param name="passwd" optional="1">passwd</param><param name="acct" optional="1">acct</param>

24284

<insert>login(user, [passwd], [acct])</insert><dialog title="Insert login">login(%0, %1, %2)</dialog><info title="Info window"></info></function>

24285

24286

24287

<description>Abort a file transfer that is in progress. Using this does not always

24288

work, but it's worth a try.</description>

24289

24290

<insert>abort()</insert><dialog title="Insert abort">abort()</dialog><info title="Info window"></info></function>

24291

24292

24293

<description>Send a simple command string to the server and return the response

24294

string.</description>

24295

<param name="commandcommand" optional="0">commandcommand</param>

24296

<insert>sendcmd(commandcommand)</insert><dialog title="Insert sendcmd">sendcmd(%0)</dialog><info title="Info window"></info></function>

24297

24298

24299

<description>Send a simple command string to the server and handle the response.

24300

Return nothing if a response code in the range 200--299 is received.

24301

Raise an exception otherwise.</description>

24302

<param name="commandcommand" optional="0">commandcommand</param>

24303

<insert>voidcmd(commandcommand)</insert><dialog title="Insert voidcmd">voidcmd(%0)</dialog><info title="Info window"></info></function>

24304

24305

24306

<description>Retrieve a file in binary transfer mode. command should be an

24307

appropriate RETR command: 'RETR filename'.

24308

The callback function is called for each block of data received,

24309

with a single string argument giving the data block.

24310

The optional maxblocksize argument specifies the maximum chunk size to

24311

read on the low-level socket object created to do the actual transfer

24312

(which will also be the largest size of the data blocks passed to

24313

callback). A reasonable default is chosen. rest means the

24314

same thing as in the transfercmd() method.</description>

24315

<param name="command" optional="0">command</param><param name="callback" optional="0">callback</param><param name="maxblocksize" optional="1">maxblocksize</param><param name="rest" optional="1">rest</param>

24316

<insert>retrbinary(command, callback, [maxblocksize], [rest])</insert><dialog title="Insert retrbinary">retrbinary(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24317

24318

24319

<description>Retrieve a file or directory listing in ASCII transfer mode.

24320

command should be an appropriate RETR command (see

24321

retrbinary()) or a LIST command (usually just the string

24322

'LIST'). The callback function is called for each line,

24323

with the trailing CRLF stripped. The default callback prints

24324

the line to sys.stdout.</description>

24325

<param name="command" optional="0">command</param><param name="callback" optional="1">callback</param>

24326

<insert>retrlines(command, [callback])</insert><dialog title="Insert retrlines">retrlines(%0, %1)</dialog><info title="Info window"></info></function>

24327

24328

24329

<description>Enable ``passive'' mode if boolean is true, other disable

24330

passive mode. (In Python 2.0 and before, passive mode was off by

24331

default; in Python 2.1 and later, it is on by default.)</description>

24332

<param name="booleanboolean" optional="0">booleanboolean</param>

24333

<insert>set_pasv(booleanboolean)</insert><dialog title="Insert set_pasv">set_pasv(%0)</dialog><info title="Info window"></info></function>

24334

24335

24336

<description>Store a file in binary transfer mode. command should be an

24337

appropriate STOR command: "STOR filename".

24338

file is an open file object which is read until using its

24339

read() method in blocks of size blocksize to provide the

24340

data to be stored. The blocksize argument defaults to 8192.

24341

Changed in version 2.1: default for blocksize added</description>

24342

<param name="command" optional="0">command</param><param name="file" optional="0">file</param><param name="blocksize" optional="1">blocksize</param>

24343

<insert>storbinary(command, file, [blocksize])</insert><dialog title="Insert storbinary">storbinary(%0, %1, %2)</dialog><info title="Info window"></info></function>

24344

24345

24346

<description>Store a file in ASCII transfer mode. command should be an

24347

appropriate STOR command (see storbinary()). Lines are

24348

read until from the open file object file using its

24349

readline() method to provide the data to be stored.</description>

24350

<param name="command" optional="0">command</param><param name="file file" optional="0">file file</param>

24351

<insert>storlines(command, file file)</insert><dialog title="Insert storlines">storlines(%0, %1)</dialog><info title="Info window"></info></function>

24352

24353

24354

<description>Initiate a transfer over the data connection. If the transfer is

24355

active, send a EPRT or PORT command and the transfer command specified

24356

by cmd, and accept the connection. If the server is passive,

24357

send a EPSV or PASV command, connect to it, and start the transfer

24358

command. Either way, return the socket for the connection.

24359

If optional rest is given, a REST command is

24360

sent to the server, passing rest as an argument. rest is

24361

usually a byte offset into the requested file, telling the server to

24362

restart sending the file's bytes at the requested offset, skipping

24363

over the initial bytes. Note however that RFC

24364

959 requires only that rest be a string containing characters

24365

in the printable range from ASCII code 33 to ASCII code 126. The

24366

transfercmd() method, therefore, converts

24367

rest to a string, but no check is

24368

performed on the string's contents. If the server does

24369

not recognize the REST command, an

24370

error_reply exception will be raised. If this happens,

24371

simply call transfercmd() without a rest argument.</description>

24372

24373

<insert>transfercmd(cmd, [rest])</insert><dialog title="Insert transfercmd">transfercmd(%0, %1)</dialog><info title="Info window"></info></function>

24374

24375

24376

<description>Like transfercmd(), but returns a tuple of the data

24377

connection and the expected size of the data. If the expected size

24378

could not be computed, None will be returned as the expected

24379

size. cmd and rest means the same thing as in

24380

transfercmd().</description>

24381

24382

<insert>ntransfercmd(cmd, [rest])</insert><dialog title="Insert ntransfercmd">ntransfercmd(%0, %1)</dialog><info title="Info window"></info></function>

24383

24384

24385

<description>Return a list of files as returned by the NLST command. The

24386

optional argument is a directory to list (default is the current

24387

server directory). Multiple arguments can be used to pass

24388

non-standard options to the NLST command.</description>

24389

<param name="argument" optional="0">argument</param><param name="ldots" optional="1">ldots</param>

24390

<insert>nlst(argument, [ldots])</insert><dialog title="Insert nlst">nlst(%0, %1)</dialog><info title="Info window"></info></function>

24391

24392

24393

<description>Produce a directory listing as returned by the LIST command,

24394

printing it to standard output. The optional argument is a

24395

directory to list (default is the current server directory). Multiple

24396

arguments can be used to pass non-standard options to the LIST

24397

command. If the last argument is a function, it is used as a

24398

callback function as for retrlines(); the default

24399

prints to sys.stdout. This method returns None.</description>

24400

<param name="argument" optional="0">argument</param><param name="ldots" optional="1">ldots</param>

24401

<insert>dir(argument, [ldots])</insert><dialog title="Insert dir">dir(%0, %1)</dialog><info title="Info window"></info></function>

24402

24403

24404

<description>Rename file fromname on the server to toname.</description>

24405

<param name="fromname" optional="0">fromname</param><param name="toname toname" optional="0">toname toname</param>

24406

<insert>rename(fromname, toname toname)</insert><dialog title="Insert rename">rename(%0, %1)</dialog><info title="Info window"></info></function>

24407

24408

24409

<description>Remove the file named filename from the server. If successful,

24410

returns the text of the response, otherwise raises

24411

error_perm on permission errors or

24412

error_reply on other errors.</description>

24413

<param name="filenamefilename" optional="0">filenamefilename</param>

24414

<insert>delete(filenamefilename)</insert><dialog title="Insert delete">delete(%0)</dialog><info title="Info window"></info></function>

24415

24416

24417

<description>Set the current directory on the server.</description>

24418

<param name="pathnamepathname" optional="0">pathnamepathname</param>

24419

<insert>cwd(pathnamepathname)</insert><dialog title="Insert cwd">cwd(%0)</dialog><info title="Info window"></info></function>

24420

24421

24422

<description>Create a new directory on the server.</description>

24423

<param name="pathnamepathname" optional="0">pathnamepathname</param>

24424

<insert>mkd(pathnamepathname)</insert><dialog title="Insert mkd">mkd(%0)</dialog><info title="Info window"></info></function>

24425

24426

24427

<description>Return the pathname of the current directory on the server.</description>

24428

24429

24430

24431

24432

<description>Remove the directory named dirname on the server.</description>

24433

<param name="dirnamedirname" optional="0">dirnamedirname</param>

24434

<insert>rmd(dirnamedirname)</insert><dialog title="Insert rmd">rmd(%0)</dialog><info title="Info window"></info></function>

24435

24436

24437

<description>Request the size of the file named filename on the server. On

24438

success, the size of the file is returned as an integer, otherwise

24439

None is returned. Note that the SIZE command is not standardized, but is supported by many common server implementations.</description>

24440

<param name="filenamefilename" optional="0">filenamefilename</param>

24441

<insert>size(filenamefilename)</insert><dialog title="Insert size">size(%0)</dialog><info title="Info window"></info></function>

24442

24443

24444

<description>Send a QUIT command to the server and close the connection.

24445

This is the ``polite'' way to close a connection, but it may raise an

24446

exception of the server reponds with an error to the

24447

QUIT command. This implies a call to the close()

24448

method which renders the FTP instance useless for subsequent

24449

calls (see below).</description>

24450

24451

24452

24453

24454

<description>Close the connection unilaterally. This should not be applied to an

24455

already closed connection such as after a successful call to

24456

quit(). After this call the FTP instance should not

24457

be used any more (after a call to close() or

24458

quit() you cannot reopen the connection by issuing another

24459

login() method).</description>

24460

24461

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

24462

24463

</group>

24464

</group>

24465

24466

<description>Gopher protocol client (requires sockets).

24467

This module provides a minimal implementation of client side of the

24468

Gopher protocol. It is used by the module urllib to

24469

handle URLs that use the Gopher protocol.

24470

The module defines the following functions:

24471

</description>

24472

24473

<description>Send a selector string to the gopher server at host and

24474

port (default 70). Returns an open file object from

24475

which the returned document can be read.</description>

24476

<param name="selector" optional="0">selector</param><param name="host" optional="0">host</param><param name="port" optional="1">port</param>

24477

<insert>send_selector(selector, host, [port])</insert><dialog title="Insert send_selector">send_selector(%0, %1, %2)</dialog><info title="Info window"></info></function>

24478

24479

24480

<description>Send a selector string and a query string to a gopher

24481

server at host and port (default 70). Returns an

24482

open file object from which the returned document can be read.</description>

24483

<param name="selector" optional="0">selector</param><param name="query" optional="0">query</param><param name="host" optional="0">host</param><param name="port" optional="1">port</param>

24484

<insert>send_query(selector, query, host, [port])</insert><dialog title="Insert send_query">send_query(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24485

24486

</group>

24487

24488

<description>POP3 protocol client (requires sockets).

24489

%By Andrew T. Csillag

24490

%Even though I put it into LaTeX, I cannot really claim that I wrote

24491

%it since I just stole most of it from the poplib.py source code and

24492

%the imaplib ``chapter''.

24493

%Revised by ESR, January 2000

24494

This module defines a class, POP3, which encapsulates a

24495

connection to a POP3 server and implements the protocol as defined in

24496

1725. The POP3 class supports both the minimal and

24497

optional command sets. Additionally, this module provides a class

24498

POP3_SSL, which provides support for connecting to POP3

24499

servers that use SSL as an underlying protocol layer.

24500

Note that POP3, though widely supported, is obsolescent. The

24501

implementation quality of POP3 servers varies widely, and too many are

24502

quite poor. If your mailserver supports IMAP, you would be better off

24503

using the imaplib.IMAP4 class, as IMAP

24504

servers tend to be better implemented.

24505

A single class is provided by the poplib module:

24506

</description>

24507

24508

<description>This class implements the actual POP3 protocol. The connection is

24509

created when the instance is initialized.

24510

If port is omitted, the standard POP3 port (110) is used.</description>

24511

24512

24513

24514

24515

<description>This is a subclass of POP3 that connects to the server over an

24516

SSL encrypted socket. If port is not specified, 995, the

24517

standard POP3-over-SSL port is used. keyfile and certfile

24518

are also optional - they can contain a PEM formatted private key and

24519

certificate chain file for the SSL connection.

24520

New in version 2.4</description>

24521

<param name="host" optional="0">host</param><param name="port" optional="1">port</param><param name="keyfile" optional="1">keyfile</param><param name="certfile" optional="1">certfile</param>

24522

<insert>POP3_SSL(host, [port], [keyfile], [certfile])</insert><dialog title="Insert POP3_SSL">POP3_SSL(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24523

24524

24525

<description>All POP3 commands are represented by methods of the same name,

24526

in lower-case; most return the response text sent by the server.

24527

An POP3 instance has the following methods:

24528

</description>

24529

24530

<description>Set the instance's debugging level. This controls the amount of

24531

debugging output printed. The default, 0, produces no

24532

debugging output. A value of 1 produces a moderate amount of

24533

debugging output, generally a single line per request. A value of

24534

2 or higher produces the maximum amount of debugging output,

24535

logging each line sent and received on the control connection.</description>

24536

<param name="levellevel" optional="0">levellevel</param>

24537

<insert>set_debuglevel(levellevel)</insert><dialog title="Insert set_debuglevel">set_debuglevel(%0)</dialog><info title="Info window"></info></function>

24538

24539

24540

<description>Returns the greeting string sent by the POP3 server.</description>

24541

24542

<insert>getwelcome()</insert><dialog title="Insert getwelcome">getwelcome()</dialog><info title="Info window"></info></function>

24543

24544

24545

<description>Send user command, response should indicate that a password is required.</description>

24546

<param name="usernameusername" optional="0">usernameusername</param>

24547

<insert>user(usernameusername)</insert><dialog title="Insert user">user(%0)</dialog><info title="Info window"></info></function>

24548

24549

24550

<description>Send password, response includes message count and mailbox size.

24551

Note: the mailbox on the server is locked until quit() is

24552

called.</description>

24553

<param name="passwordpassword" optional="0">passwordpassword</param>

24554

<insert>pass_(passwordpassword)</insert><dialog title="Insert pass_">pass_(%0)</dialog><info title="Info window"></info></function>

24555

24556

24557

<description>Use the more secure APOP authentication to log into the POP3 server.</description>

24558

<param name="user" optional="0">user</param><param name="secret secret" optional="0">secret secret</param>

24559

<insert>apop(user, secret secret)</insert><dialog title="Insert apop">apop(%0, %1)</dialog><info title="Info window"></info></function>

24560

24561

24562

<description>Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.</description>

24563

<param name="useruser" optional="0">useruser</param>

24564

<insert>rpop(useruser)</insert><dialog title="Insert rpop">rpop(%0)</dialog><info title="Info window"></info></function>

24565

24566

24567

<description>Get mailbox status. The result is a tuple of 2 integers:

24568

(message count, mailbox size).</description>

24569

24570

24571

24572

24573

<description>Request message list, result is in the form

24574

(response, ['mesg_num octets', ...]). If which is

24575

set, it is the message to list.</description>

24576

<param name="which" optional="0">which</param>

24577

<insert>list(which)</insert><dialog title="Insert list">list(%0)</dialog><info title="Info window"></info></function>

24578

24579

24580

<description>Retrieve whole message number which, and set its seen flag.

24581

Result is in form (response, ['line', ...], octets).</description>

24582

<param name="whichwhich" optional="0">whichwhich</param>

24583

<insert>retr(whichwhich)</insert><dialog title="Insert retr">retr(%0)</dialog><info title="Info window"></info></function>

24584

24585

24586

<description>Flag message number which for deletion. On most servers

24587

deletions are not actually performed until QUIT (the major exception is

24588

Eudora QPOP, which deliberately violates the RFCs by doing pending

24589

deletes on any disconnect).</description>

24590

<param name="whichwhich" optional="0">whichwhich</param>

24591

<insert>dele(whichwhich)</insert><dialog title="Insert dele">dele(%0)</dialog><info title="Info window"></info></function>

24592

24593

24594

<description>Remove any deletion marks for the mailbox.</description>

24595

24596

24597

24598

24599

<description>Do nothing. Might be used as a keep-alive.</description>

24600

24601

24602

24603

24604

<description>Signoff: commit changes, unlock mailbox, drop connection.</description>

24605

24606

24607

24608

24609

<description>Retrieves the message header plus howmuch lines of the message

24610

after the header of message number which. Result is in form

24611

(response, ['line', ...], octets).

24612

The POP3 TOP command this method uses, unlike the RETR command,

24613

doesn't set the message's seen flag; unfortunately, TOP is poorly

24614

specified in the RFCs and is frequently broken in off-brand servers.

24615

Test this method by hand against the POP3 servers you will use before

24616

trusting it.</description>

24617

<param name="which" optional="0">which</param><param name="howmuch howmuch" optional="0">howmuch howmuch</param>

24618

<insert>top(which, howmuch howmuch)</insert><dialog title="Insert top">top(%0, %1)</dialog><info title="Info window"></info></function>

24619

24620

24621

<description>Return message digest (unique id) list.

24622

If which is specified, result contains the unique id for that

24623

message in the form 'response mesgnum uid,

24624

otherwise result is list (response, ['mesgnum uid', ...],

24625

octets).</description>

24626

<param name="which" optional="0">which</param>

24627

<insert>uidl(which)</insert><dialog title="Insert uidl">uidl(%0)</dialog><info title="Info window"></info></function>

24628

24629

</group>

24630

24631

</group>

24632

</group>

24633

24634

<description>IMAP4 protocol client (requires sockets).

24635

% Based on HTML documentation by Piers Lauder <piers@communitysolutions.com.au>;

24636

% converted by Fred L. Drake, Jr. <fdrake@acm.org>.

24637

% Revised by ESR, January 2000.

24638

% 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

24639

connection to an IMAP4 server and implement a large subset of the

24640

IMAP4rev1 client protocol as defined in 2060. It is backward

24641

compatible with IMAP4 (1730) servers, but note that the

24642

STATUS command is not supported in IMAP4.

24643

Three classes are provided by the imaplib module, IMAP4 is the base class:

24644

</description>

24645

24646

<description>This class implements the actual IMAP4 protocol. The connection is

24647

created and protocol version (IMAP4 or IMAP4rev1) is determined when

24648

the instance is initialized.

24649

If host is not specified, '' (the local host) is used.

24650

If port is omitted, the standard IMAP4 port (143) is used.</description>

24651

24652

24653

24654

24655

<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).

24656

If host is not specified, '' (the local host) is used.

24657

If port is omitted, the standard IMAP4-over-SSL port (993) is used.

24658

keyfile and certfile are also optional - they can contain a PEM formatted

24659

private key and certificate chain file for the SSL connection.</description>

24660

<param name="host" optional="0">host</param><param name="port" optional="1">port</param><param name="keyfile" optional="1">keyfile</param><param name="certfile" optional="1">certfile</param>

24661

<insert>IMAP4_SSL(host, [port], [keyfile], [certfile])</insert><dialog title="Insert IMAP4_SSL">IMAP4_SSL(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24662

24663

24664

<description>This is a subclass derived from IMAP4 that connects

24665

to the stdin/stdout file descriptors created by passing command to os.popen2().

24666

New in version 2.3</description>

24667

<param name="commandcommand" optional="0">commandcommand</param>

24668

<insert>IMAP4_stream(commandcommand)</insert><dialog title="Insert IMAP4_stream">IMAP4_stream(%0)</dialog><info title="Info window"></info></function>

24669

24670

24671

<description>Converts an IMAP4 INTERNALDATE string to Coordinated Universal

24672

Time. Returns a time module tuple.</description>

24673

<param name="datestrdatestr" optional="0">datestrdatestr</param>

24674

<insert>Internaldate2tuple(datestrdatestr)</insert><dialog title="Insert Internaldate2tuple">Internaldate2tuple(%0)</dialog><info title="Info window"></info></function>

24675

24676

24677

<description>Converts an integer into a string representation using characters

24678

from the set [A .. P].</description>

24679

<param name="numnum" optional="0">numnum</param>

24680

<insert>Int2AP(numnum)</insert><dialog title="Insert Int2AP">Int2AP(%0)</dialog><info title="Info window"></info></function>

24681

24682

24683

<description>Converts an IMAP4 FLAGS response to a tuple of individual

24684

flags.</description>

24685

<param name="flagstrflagstr" optional="0">flagstrflagstr</param>

24686

<insert>ParseFlags(flagstrflagstr)</insert><dialog title="Insert ParseFlags">ParseFlags(%0)</dialog><info title="Info window"></info></function>

24687

24688

24689

<description>Converts a time module tuple to an IMAP4

24690

INTERNALDATE representation. Returns a string in the form:

24691

"DD-Mmm-YYYY HH:MM:SS +HHMM" (including double-quotes).</description>

24692

<param name="date_timedate_time" optional="0">date_timedate_time</param>

24693

<insert>Time2Internaldate(date_timedate_time)</insert><dialog title="Insert Time2Internaldate">Time2Internaldate(%0)</dialog><info title="Info window"></info></function>

24694

24695

24696

<description>All IMAP4rev1 commands are represented by methods of the same name,

24697

either upper-case or lower-case.

24698

All arguments to commands are converted to strings, except for

24699

AUTHENTICATE, and the last argument to APPEND which is

24700

passed as an IMAP4 literal. If necessary (the string contains IMAP4

24701

protocol-sensitive characters and isn't enclosed with either

24702

parentheses or double quotes) each string is quoted. However, the

24703

password argument to the LOGIN command is always quoted.

24704

If you want to avoid having an argument string quoted

24705

(eg: the flags argument to STORE) then enclose the string in

24706

parentheses (eg: r'(\Deleted)').

24707

Each command returns a tuple: (type, [data,

24708

...]) where type is usually 'OK' or 'NO',

24709

and data is either the text from the command response, or

24710

mandated results from the command. Each data

24711

is either a string, or a tuple. If a tuple, then the first part

24712

is the header of the response, and the second part contains

24713

the data (ie: 'literal' value).

24714

An IMAP4 instance has the following methods:

24715

</description>

24716

24717

<description>Append message to named mailbox.</description>

24718

<param name="mailbox" optional="0">mailbox</param><param name="flags" optional="0">flags</param><param name="date_time" optional="0">date_time</param><param name="message message" optional="0">message message</param>

24719

<insert>append(mailbox, flags, date_time, message message)</insert><dialog title="Insert append">append(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24720

24721

24722

<description>Authenticate command --- requires response processing. This is

24723

currently unimplemented, and raises an exception.</description>

24724

<param name="funcfunc" optional="0">funcfunc</param>

24725

<insert>authenticate(funcfunc)</insert><dialog title="Insert authenticate">authenticate(%0)</dialog><info title="Info window"></info></function>

24726

24727

24728

<description>Checkpoint mailbox on server.</description>

24729

24730

<insert>check()</insert><dialog title="Insert check">check()</dialog><info title="Info window"></info></function>

24731

24732

24733

<description>Close currently selected mailbox. Deleted messages are removed from

24734

writable mailbox. This is the recommended command before

24735

LOGOUT.</description>

24736

24737

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

24738

24739

24740

<description>Copy message_set messages onto end of new_mailbox.</description>

24741

<param name="message_set" optional="0">message_set</param><param name="new_mailbox new_mailbox" optional="0">new_mailbox new_mailbox</param>

24742

<insert>copy(message_set, new_mailbox new_mailbox)</insert><dialog title="Insert copy">copy(%0, %1)</dialog><info title="Info window"></info></function>

24743

24744

24745

<description>Create new mailbox named mailbox.</description>

24746

<param name="mailboxmailbox" optional="0">mailboxmailbox</param>

24747

<insert>create(mailboxmailbox)</insert><dialog title="Insert create">create(%0)</dialog><info title="Info window"></info></function>

24748

24749

24750

<description>Delete old mailbox named mailbox.</description>

24751

<param name="mailboxmailbox" optional="0">mailboxmailbox</param>

24752

<insert>delete(mailboxmailbox)</insert><dialog title="Insert delete">delete(%0)</dialog><info title="Info window"></info></function>

24753

24754

24755

<description>Permanently remove deleted items from selected mailbox. Generates an

24756

EXPUNGE response for each deleted message. Returned data

24757

contains a list of EXPUNGE message numbers in order

24758

received.</description>

24759

24760

<insert>expunge()</insert><dialog title="Insert expunge">expunge()</dialog><info title="Info window"></info></function>

24761

24762

24763

<description>Fetch (parts of) messages. message_parts should be

24764

a string of message part names enclosed within parentheses,

24765

eg: "(UID BODY[TEXT])". Returned data are tuples

24766

of message part envelope and data.</description>

24767

<param name="message_set" optional="0">message_set</param><param name="message_parts message_parts" optional="0">message_parts message_parts</param>

24768

<insert>fetch(message_set, message_parts message_parts)</insert><dialog title="Insert fetch">fetch(%0, %1)</dialog><info title="Info window"></info></function>

24769

24770

24771

<description>Get the ACLs for mailbox.

24772

The method is non-standard, but is supported by the Cyrus server.</description>

24773

<param name="mailboxmailbox" optional="0">mailboxmailbox</param>

24774

<insert>getacl(mailboxmailbox)</insert><dialog title="Insert getacl">getacl(%0)</dialog><info title="Info window"></info></function>

24775

24776

24777

<description>Get the quota root's resource usage and limits.

24778

This method is part of the IMAP4 QUOTA extension defined in rfc2087.

24779

New in version 2.3</description>

24780

<param name="rootroot" optional="0">rootroot</param>

24781

<insert>getquota(rootroot)</insert><dialog title="Insert getquota">getquota(%0)</dialog><info title="Info window"></info></function>

24782

24783

24784

<description>Get the list of quota roots for the named mailbox.

24785

This method is part of the IMAP4 QUOTA extension defined in rfc2087.

24786

New in version 2.3</description>

24787

<param name="mailboxmailbox" optional="0">mailboxmailbox</param>

24788

<insert>getquotaroot(mailboxmailbox)</insert><dialog title="Insert getquotaroot">getquotaroot(%0)</dialog><info title="Info window"></info></function>

24789

24790

24791

<description>List mailbox names in directory matching

24792

pattern. directory defaults to the top-level mail

24793

folder, and pattern defaults to match anything. Returned data

24794

contains a list of LIST responses.</description>

24795

<param name="directory" optional="0">directory</param><param name="pattern" optional="1">pattern</param>

24796

<insert>list(directory, [pattern])</insert><dialog title="Insert list">list(%0, %1)</dialog><info title="Info window"></info></function>

24797

24798

24799

<description>Identify the client using a plaintext password.

24800

The password will be quoted.</description>

24801

<param name="user" optional="0">user</param><param name="password password" optional="0">password password</param>

24802

<insert>login(user, password password)</insert><dialog title="Insert login">login(%0, %1)</dialog><info title="Info window"></info></function>

24803

24804

24805

<description>Force use of CRAM-MD5 authentication when identifying the client to protect the password.

24806

Will only work if the server CAPABILITY response includes the phrase AUTH=CRAM-MD5.

24807

New in version 2.3</description>

24808

<param name="user" optional="0">user</param><param name="password password" optional="0">password password</param>

24809

<insert>login_cram_md5(user, password password)</insert><dialog title="Insert login_cram_md5">login_cram_md5(%0, %1)</dialog><info title="Info window"></info></function>

24810

24811

24812

<description>Shutdown connection to server. Returns server BYE response.</description>

24813

24814

<insert>logout()</insert><dialog title="Insert logout">logout()</dialog><info title="Info window"></info></function>

24815

24816

24817

<description>List subscribed mailbox names in directory matching pattern.

24818

directory defaults to the top level directory and

24819

pattern defaults to match any mailbox.

24820

Returned data are tuples of message part envelope and data.</description>

24821

<param name="directory" optional="0">directory</param><param name="pattern" optional="1">pattern</param>

24822

<insert>lsub(directory, [pattern])</insert><dialog title="Insert lsub">lsub(%0, %1)</dialog><info title="Info window"></info></function>

24823

24824

24825

<description>Send NOOP to server.</description>

24826

24827

24828

24829

24830

<description>Opens socket to port at host.

24831

The connection objects established by this method

24832

will be used in the read, readline, send, and shutdown methods.

24833

You may override this method.</description>

24834

24835

24836

24837

24838

<description>Fetch truncated part of a message.

24839

Returned data is a tuple of message part envelope and data.</description>

24840

<param name="message_num" optional="0">message_num</param><param name="message_part" optional="0">message_part</param><param name="start" optional="0">start</param><param name="length length" optional="0">length length</param>

24841

<insert>partial(message_num, message_part, start, length length)</insert><dialog title="Insert partial">partial(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24842

24843

24844

<description>Assume authentication as user.

24845

Allows an authorised administrator to proxy into any user's mailbox.

24846

New in version 2.3</description>

24847

<param name="useruser" optional="0">useruser</param>

24848

<insert>proxyauth(useruser)</insert><dialog title="Insert proxyauth">proxyauth(%0)</dialog><info title="Info window"></info></function>

24849

24850

24851

<description>Reads size bytes from the remote server.

24852

You may override this method.</description>

24853

<param name="sizesize" optional="0">sizesize</param>

24854

<insert>read(sizesize)</insert><dialog title="Insert read">read(%0)</dialog><info title="Info window"></info></function>

24855

24856

24857

<description>Reads one line from the remote server.

24858

You may override this method.</description>

24859

24860

<insert>readline()</insert><dialog title="Insert readline">readline()</dialog><info title="Info window"></info></function>

24861

24862

24863

<description>Prompt server for an update. Returned data is None if no new

24864

messages, else value of RECENT response.</description>

24865

24866

<insert>recent()</insert><dialog title="Insert recent">recent()</dialog><info title="Info window"></info></function>

24867

24868

24869

<description>Rename mailbox named oldmailbox to newmailbox.</description>

24870

<param name="oldmailbox" optional="0">oldmailbox</param><param name="newmailbox newmailbox" optional="0">newmailbox newmailbox</param>

24871

<insert>rename(oldmailbox, newmailbox newmailbox)</insert><dialog title="Insert rename">rename(%0, %1)</dialog><info title="Info window"></info></function>

24872

24873

24874

<description>Return data for response code if received, or

24875

None. Returns the given code, instead of the usual type.</description>

24876

<param name="codecode" optional="0">codecode</param>

24877

<insert>response(codecode)</insert><dialog title="Insert response">response(%0)</dialog><info title="Info window"></info></function>

24878

24879

24880

<description>Search mailbox for matching messages. Returned data contains a space

24881

separated list of matching message numbers. charset may be

24882

None, in which case no CHARSET will be specified in the

24883

request to the server. The IMAP protocol requires that at least one

24884

criterion be specified; an exception will be raised when the server

24885

returns an error.

24886

Example:

24887

# M is a connected IMAP4 instance...

24888

msgnums = M.search(None, 'FROM', '"LDJ"')

24889

# or:

24890

msgnums = M.search(None, '(FROM "LDJ")')

24891

</description>

24892

<param name="charset" optional="0">charset</param><param name="criterion" optional="0">criterion</param><param name="..." optional="1">...</param>

24893

<insert>search(charset, criterion, [...])</insert><dialog title="Insert search">search(%0, %1, %2)</dialog><info title="Info window"></info></function>

24894

24895

24896

<description>Select a mailbox. Returned data is the count of messages in

24897

mailbox (EXISTS response). The default mailbox

24898

is 'INBOX'. If the readonly flag is set, modifications

24899

to the mailbox are not allowed.</description>

24900

<param name="mailbox" optional="0">mailbox</param><param name="readonly" optional="1">readonly</param>

24901

<insert>select(mailbox, [readonly])</insert><dialog title="Insert select">select(%0, %1)</dialog><info title="Info window"></info></function>

24902

24903

24904

<description>Sends data to the remote server.

24905

You may override this method.</description>

24906

<param name="datadata" optional="0">datadata</param>

24907

<insert>send(datadata)</insert><dialog title="Insert send">send(%0)</dialog><info title="Info window"></info></function>

24908

24909

24910

<description>Set an ACL for mailbox.

24911

The method is non-standard, but is supported by the Cyrus server.</description>

24912

<param name="mailbox" optional="0">mailbox</param><param name="who" optional="0">who</param><param name="what what" optional="0">what what</param>

24913

<insert>setacl(mailbox, who, what what)</insert><dialog title="Insert setacl">setacl(%0, %1, %2)</dialog><info title="Info window"></info></function>

24914

24915

24916

<description>Set the quota root's resource limits.

24917

This method is part of the IMAP4 QUOTA extension defined in rfc2087.

24918

New in version 2.3</description>

24919

<param name="root" optional="0">root</param><param name="limits limits" optional="0">limits limits</param>

24920

<insert>setquota(root, limits limits)</insert><dialog title="Insert setquota">setquota(%0, %1)</dialog><info title="Info window"></info></function>

24921

24922

24923

<description>Close connection established in open.

24924

You may override this method.</description>

24925

24926

<insert>shutdown()</insert><dialog title="Insert shutdown">shutdown()</dialog><info title="Info window"></info></function>

24927

24928

24929

<description>Returns socket instance used to connect to server.</description>

24930

24931

<insert>socket()</insert><dialog title="Insert socket">socket()</dialog><info title="Info window"></info></function>

24932

24933

24934

<description>The sort command is a variant of search with sorting semantics for

24935

the results. Returned data contains a space

24936

separated list of matching message numbers.

24937

Sort has two arguments before the search_criterion

24938

argument(s); a parenthesized list of sort_criteria, and the searching charset.

24939

Note that unlike search, the searching charset argument is mandatory.

24940

There is also a uid sort command which corresponds to sort the way

24941

that uid search corresponds to search.

24942

The sort command first searches the mailbox for messages that

24943

match the given searching criteria using the charset argument for

24944

the interpretation of strings in the searching criteria. It then

24945

returns the numbers of matching messages.

24946

This is an IMAP4rev1 extension command.</description>

24947

<param name="sort_criteria" optional="0">sort_criteria</param><param name="charset" optional="0">charset</param><param name="search_criterion" optional="0">search_criterion</param><param name="..." optional="1">...</param>

24948

<insert>sort(sort_criteria, charset, search_criterion, [...])</insert><dialog title="Insert sort">sort(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24949

24950

24951

<description>Request named status conditions for mailbox.</description>

24952

<param name="mailbox" optional="0">mailbox</param><param name="names names" optional="0">names names</param>

24953

<insert>status(mailbox, names names)</insert><dialog title="Insert status">status(%0, %1)</dialog><info title="Info window"></info></function>

24954

24955

24956

<description>Alters flag dispositions for messages in mailbox.</description>

24957

<param name="message_set" optional="0">message_set</param><param name="command" optional="0">command</param><param name="flag_list flag_list" optional="0">flag_list flag_list</param>

24958

<insert>store(message_set, command, flag_list flag_list)</insert><dialog title="Insert store">store(%0, %1, %2)</dialog><info title="Info window"></info></function>

24959

24960

24961

<description>Subscribe to new mailbox.</description>

24962

<param name="mailboxmailbox" optional="0">mailboxmailbox</param>

24963

<insert>subscribe(mailboxmailbox)</insert><dialog title="Insert subscribe">subscribe(%0)</dialog><info title="Info window"></info></function>

24964

24965

24966

<description>The thread command is a variant of search with threading semantics for

24967

the results. Returned data contains a space

24968

separated list of thread members.

24969

Thread members consist of zero or more messages numbers, delimited by spaces,

24970

indicating successive parent and child.

24971

Thread has two arguments before the search_criterion

24972

argument(s); a threading_algorithm, and the searching charset.

24973

Note that unlike search, the searching charset argument is mandatory.

24974

There is also a uid thread command which corresponds to thread the way

24975

that uid search corresponds to search.

24976

The thread command first searches the mailbox for messages that

24977

match the given searching criteria using the charset argument for

24978

the interpretation of strings in the searching criteria. It thren

24979

returns the matching messages threaded according to the specified

24980

threading algorithm.

24981

This is an IMAP4rev1 extension command. New in version 2.4</description>

24982

<param name="threading_algorithm" optional="0">threading_algorithm</param><param name="charset" optional="0">charset</param><param name="search_criterion" optional="0">search_criterion</param><param name="..." optional="1">...</param>

24983

<insert>thread(threading_algorithm, charset, search_criterion, [...])</insert><dialog title="Insert thread">thread(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

24984

24985

24986

<description>Execute command args with messages identified by UID, rather than

24987

message number. Returns response appropriate to command. At least

24988

one argument must be supplied; if none are provided, the server will

24989

return an error and an exception will be raised.</description>

24990

<param name="command" optional="0">command</param><param name="arg" optional="0">arg</param><param name="..." optional="1">...</param>

24991

<insert>uid(command, arg, [...])</insert><dialog title="Insert uid">uid(%0, %1, %2)</dialog><info title="Info window"></info></function>

24992

24993

24994

<description>Unsubscribe from old mailbox.</description>

24995

<param name="mailboxmailbox" optional="0">mailboxmailbox</param>

24996

<insert>unsubscribe(mailboxmailbox)</insert><dialog title="Insert unsubscribe">unsubscribe(%0)</dialog><info title="Info window"></info></function>

24997

24998

24999

<description>Allow simple extension commands notified by server in

25000

CAPABILITY response.</description>

25001

25002

<insert>xatom(name, [arg], [...])</insert><dialog title="Insert xatom">xatom(%0, %1, %2)</dialog><info title="Info window"></info></function>

25003

25004

25005

<description>Returns SSLObject instance used for the secure connection with the server.</description>

25006

25007

25008

25009

</group>

25010

25011

</group>

25012

</group>

25013

25014

<description>NNTP protocol client (requires sockets).

25015

</description>

25016

25017

<description>Return a new instance of the NNTP class, representing a

25018

connection to the NNTP server running on host host, listening at

25019

port port. The default port is 119. If the optional

25020

user and password are provided, or if suitable credentials are present in ~/.netrc,

25021

the AUTHINFO USER and AUTHINFO PASS commands are used to

25022

identify and authenticate the user to the server. If the optional

25023

flag readermode is true, then a mode reader command is

25024

sent before authentication is performed. Reader mode is sometimes

25025

necessary if you are connecting to an NNTP server on the local machine

25026

and intend to call reader-specific commands, such as group. If

25027

you get unexpected NNTPPermanentErrors, you might need to set

25028

readermode. readermode defaults to None.</description>

25029

<param name="host" optional="0">host</param><param name="port" optional="1">port</param><param name="user" optional="1">user</param><param name="password" optional="1">password</param><param name="readermode" optional="1">readermode</param>

25030

<insert>NNTP(host, [port], [user], [password], [readermode])</insert><dialog title="Insert NNTP">NNTP(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

25031

25032

25033

<description>Derived from the standard exception Exception, this is the base

25034

class for all exceptions raised by the nntplib module.</description>

25035

25036

<insert>NNTPError()</insert><dialog title="Insert NNTPError">NNTPError()</dialog><info title="Info window"></info></function>

25037

25038

25039

<description>Exception raised when an unexpected reply is received from the

25040

server. For backwards compatibility, the exception error_reply

25041

is equivalent to this class.</description>

25042

25043

<insert>NNTPReplyError()</insert><dialog title="Insert NNTPReplyError">NNTPReplyError()</dialog><info title="Info window"></info></function>

25044

25045

25046

<description>Exception raised when an error code in the range 400--499 is

25047

received. For backwards compatibility, the exception

25048

error_temp is equivalent to this class.</description>

25049

25050

<insert>NNTPTemporaryError()</insert><dialog title="Insert NNTPTemporaryError">NNTPTemporaryError()</dialog><info title="Info window"></info></function>

25051

25052

25053

<description>Exception raised when an error code in the range 500--599 is

25054

received. For backwards compatibility, the exception

25055

error_perm is equivalent to this class.</description>

25056

25057

<insert>NNTPPermanentError()</insert><dialog title="Insert NNTPPermanentError">NNTPPermanentError()</dialog><info title="Info window"></info></function>

25058

25059

25060

<description>Exception raised when a reply is received from the server that does

25061

not begin with a digit in the range 1--5. For backwards

25062

compatibility, the exception error_proto is equivalent to this

25063

class.</description>

25064

25065

<insert>NNTPProtocolError()</insert><dialog title="Insert NNTPProtocolError">NNTPProtocolError()</dialog><info title="Info window"></info></function>

25066

25067

25068

<description>Exception raised when there is some error in the response data. For

25069

backwards compatibility, the exception error_data is

25070

equivalent to this class.</description>

25071

25072

<insert>NNTPDataError()</insert><dialog title="Insert NNTPDataError">NNTPDataError()</dialog><info title="Info window"></info></function>

25073

25074

25075

<description>NNTP instances have the following methods. The response that is

25076

returned as the first item in the return tuple of almost all methods

25077

is the server's response: a string beginning with a three-digit code.

25078

If the server's response indicates an error, the method raises one of

25079

the above exceptions.

25080

</description>

25081

25082

<description>Return the welcome message sent by the server in reply to the initial

25083

connection. (This message sometimes contains disclaimers or help

25084

information that may be relevant to the user.)</description>

25085

25086

<insert>getwelcome()</insert><dialog title="Insert getwelcome">getwelcome()</dialog><info title="Info window"></info></function>

25087

25088

25089

<description>Set the instance's debugging level. This controls the amount of

25090

debugging output printed. The default, 0, produces no debugging

25091

output. A value of 1 produces a moderate amount of debugging

25092

output, generally a single line per request or response. A value of

25093

2 or higher produces the maximum amount of debugging output,

25094

logging each line sent and received on the connection (including

25095

message text).</description>

25096

<param name="levellevel" optional="0">levellevel</param>

25097

<insert>set_debuglevel(levellevel)</insert><dialog title="Insert set_debuglevel">set_debuglevel(%0)</dialog><info title="Info window"></info></function>

25098

25099

25100

<description>Send a NEWGROUPS command. The date argument should be a

25101

string of the form 'yymmdd' indicating the

25102

date, and time should be a string of the form

25103

'hhmmss' indicating the time. Return a pair

25104

(response, groups) where groups is a list of

25105

group names that are new since the given date and time.

25106

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

25107

calling write() on it to store the lines of the command output.

25108

If file is supplied, then the returned list is an empty list.</description>

25109

25110

<insert>newgroups(date, time, file)</insert><dialog title="Insert newgroups">newgroups(%0, %1, %2)</dialog><info title="Info window"></info></function>

25111

25112

25113

<description>Send a NEWNEWS command. Here, group is a group name or

25114

'*', and date and time have the same meaning as for

25115

newgroups(). Return a pair (response,

25116

articles) where articles is a list of article ids.

25117

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

25118

calling write() on it to store the lines of the command output.

25119

If file is supplied, then the returned list is an empty list.</description>

25120

<param name="group" optional="0">group</param><param name="date" optional="0">date</param><param name="time" optional="0">time</param><param name="file" optional="0">file</param>

25121

<insert>newnews(group, date, time, file)</insert><dialog title="Insert newnews">newnews(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

25122

25123

25124

<description>Send a LIST command. Return a pair (response,

25125

list) where list is a list of tuples. Each tuple has the

25126

form (group, last, first, flag), where

25127

group is a group name, last and first are the last

25128

and first article numbers (as strings), and flag is

25129

'y' if posting is allowed, 'n' if not, and 'm' if

25130

the newsgroup is moderated. (Note the ordering: last,

25131

first.)

25132

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

25133

calling write() on it to store the lines of the command output.

25134

If file is supplied, then the returned list is an empty list.</description>

25135

25136

25137

25138

25139

<description>Send a GROUP command, where name is the group name.

25140

Return a tuple (response, count, first,

25141

last, name) where count is the (estimated) number

25142

of articles in the group, first is the first article number in

25143

the group, last is the last article number in the group, and

25144

name is the group name. The numbers are returned as strings.</description>

25145

<param name="namename" optional="0">namename</param>

25146

<insert>group(namename)</insert><dialog title="Insert group">group(%0)</dialog><info title="Info window"></info></function>

25147

25148

25149

<description>Send a HELP command. Return a pair (response,

25150

list) where list is a list of help strings.

25151

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

25152

calling write() on it to store the lines of the command output.

25153

If file is supplied, then the returned list is an empty list.</description>

25154

25155

25156

25157

25158

<description>Send a STAT command, where id is the message id (enclosed

25159

in < and >) or an article number (as a string).

25160

Return a triple (response, number, id) where

25161

number is the article number (as a string) and id is the

25162

article id (enclosed in < and >).</description>

25163

25164

25165

25166

25167

<description>Send a NEXT command. Return as for stat().</description>

25168

25169

25170

25171

25172

<description>Send a LAST command. Return as for stat().</description>

25173

25174

25175

25176

25177

<description>Send a HEAD command, where id has the same meaning as for

25178

stat(). Return a tuple

25179

(response, number, id, list)

25180

where the first three are the same as for stat(),

25181

and list is a list of the article's headers (an uninterpreted

25182

list of lines, without trailing newlines).</description>

25183

25184

25185

25186

25187

<description>Send a BODY command, where id has the same meaning as for

25188

stat(). If the file parameter is supplied, then

25189

the body is stored in a file. If file is a string, then

25190

the method will open a file object with that name, write to it then close it.

25191

If file is a file object, then it will start calling

25192

write() on it to store the lines of the body.

25193

Return as for head(). If file is supplied, then

25194

the returned list is an empty list.</description>

25195

25196

25197

25198

25199

<description>Send an ARTICLE command, where id has the same meaning as

25200

for stat(). Return as for head().</description>

25201

25202

<insert>article(idid)</insert><dialog title="Insert article">article(%0)</dialog><info title="Info window"></info></function>

25203

25204

25205

<description>Send a SLAVE command. Return the server's response.</description>

25206

25207

<insert>slave()</insert><dialog title="Insert slave">slave()</dialog><info title="Info window"></info></function>

25208

25209

25210

<description>Send an XHDR command. This command is not defined in the RFC

25211

but is a common extension. The header argument is a header

25212

keyword, e.g. 'subject'. The string argument should have

25213

the form 'first-last' where first and

25214

last are the first and last article numbers to search. Return a

25215

pair (response, list), where list is a list of

25216

pairs (id, text), where id is an article id

25217

(as a string) and text is the text of the requested header for

25218

that article.

25219

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

25220

calling write() on it to store the lines of the command output.

25221

If file is supplied, then the returned list is an empty list.</description>

25222

<param name="header" optional="0">header</param><param name="string" optional="0">string</param><param name="file" optional="0">file</param>

25223

<insert>xhdr(header, string, file)</insert><dialog title="Insert xhdr">xhdr(%0, %1, %2)</dialog><info title="Info window"></info></function>

25224

25225

25226

<description>Post an article using the POST command. The file

25227

argument is an open file object which is read until EOF using its

25228

readline() method. It should be a well-formed news article,

25229

including the required headers. The post() method

25230

automatically escapes lines beginning with ..</description>

25231

<param name="filefile" optional="0">filefile</param>

25232

<insert>post(filefile)</insert><dialog title="Insert post">post(%0)</dialog><info title="Info window"></info></function>

25233

25234

25235

<description>Send an IHAVE command. If the response is not an error, treat

25236

file exactly as for the post() method.</description>

25237

25238

<insert>ihave(id, file file)</insert><dialog title="Insert ihave">ihave(%0, %1)</dialog><info title="Info window"></info></function>

25239

25240

25241

<description>Return a triple (response, date, time),

25242

containing the current date and time in a form suitable for the

25243

newnews() and newgroups() methods.

25244

This is an optional NNTP extension, and may not be supported by all

25245

servers.</description>

25246

25247

25248

25249

25250

<description>Process an XGTITLE command, returning a pair (response,

25251

list), where list is a list of tuples containing

25252

(name, title).

25253

% XXX huh? Should that be name, description?

25254

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

25255

calling write() on it to store the lines of the command output.

25256

If file is supplied, then the returned list is an empty list.

25257

This is an optional NNTP extension, and may not be supported by all

25258

servers.</description>

25259

25260

<insert>xgtitle(name, file)</insert><dialog title="Insert xgtitle">xgtitle(%0, %1)</dialog><info title="Info window"></info></function>

25261

25262

25263

<description>Return a pair (resp, list). list is a list

25264

of tuples, one for each article in the range delimited by the start

25265

and end article numbers. Each tuple is of the form

25266

(article number, subject, poster, date,

25267

id, references, size, lines).

25268

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

25269

calling write() on it to store the lines of the command output.

25270

If file is supplied, then the returned list is an empty list.

25271

This is an optional NNTP extension, and may not be supported by all

25272

servers.</description>

25273

<param name="start" optional="0">start</param><param name="end" optional="0">end</param><param name="file" optional="0">file</param>

25274

<insert>xover(start, end, file)</insert><dialog title="Insert xover">xover(%0, %1, %2)</dialog><info title="Info window"></info></function>

25275

25276

25277

<description>Return a pair (resp, path), where path is the

25278

directory path to the article with message ID id. This is an

25279

optional NNTP extension, and may not be supported by all servers.</description>

25280

25281

<insert>xpath(idid)</insert><dialog title="Insert xpath">xpath(%0)</dialog><info title="Info window"></info></function>

25282

25283

25284

<description>Send a QUIT command and close the connection. Once this method

25285

has been called, no other methods of the NNTP object should be called.</description>

25286

25287

25288

25289

</group>

25290

</group>

25291

25292

<description>SMTP protocol client (requires sockets).

25293

</description>

25294

25295

<description>A SMTP instance encapsulates an SMTP connection. It has

25296

methods that support a full repertoire of SMTP and ESMTP

25297

operations. If the optional host and port parameters are given, the

25298

SMTP connect() method is called with those parameters during

25299

initialization. An SMTPConnectError is raised if the

25300

specified host doesn't respond correctly.

25301

For normal use, you should only require the initialization/connect,

25302

sendmail(), and quit() methods. An example is

25303

included below.</description>

25304

<param name="host" optional="0">host</param><param name="port" optional="1">port</param><param name="local_hostname" optional="1">local_hostname</param>

25305

<insert>SMTP(host, [port], [local_hostname])</insert><dialog title="Insert SMTP">SMTP(%0, %1, %2)</dialog><info title="Info window"></info></function>

25306

25307

25308

<description>An SMTP instance has the following methods:

25309

</description>

25310

25311

<description>Set the debug output level. A true value for level results in

25312

debug messages for connection and for all messages sent to and

25313

received from the server.</description>

25314

<param name="levellevel" optional="0">levellevel</param>

25315

<insert>set_debuglevel(levellevel)</insert><dialog title="Insert set_debuglevel">set_debuglevel(%0)</dialog><info title="Info window"></info></function>

25316

25317

25318

<description>Connect to a host on a given port. The defaults are to connect to the

25319

local host at the standard SMTP port (25).

25320

If the hostname ends with a colon (:) followed by a

25321

number, that suffix will be stripped off and the number interpreted as

25322

the port number to use.

25323

This method is automatically invoked by the constructor if a

25324

host is specified during instantiation.</description>

25325

25326

<insert>connect(host, [port])</insert><dialog title="Insert connect">connect(%0, %1)</dialog><info title="Info window"></info></function>

25327

25328

25329

<description>Send a command cmd to the server. The optional argument

25330

argstring is simply concatenated to the command, separated by a

25331

space.

25332

This returns a 2-tuple composed of a numeric response code and the

25333

actual response line (multiline responses are joined into one long

25334

line.)

25335

In normal operation it should not be necessary to call this method

25336

explicitly. It is used to implement other methods and may be useful

25337

for testing private extensions.

25338

If the connection to the server is lost while waiting for the reply,

25339

SMTPServerDisconnected will be raised.</description>

25340

<param name="cmd" optional="0">cmd</param><param name="argstring" optional="1">argstring</param>

25341

<insert>docmd(cmd, [argstring])</insert><dialog title="Insert docmd">docmd(%0, %1)</dialog><info title="Info window"></info></function>

25342

25343

25344

<description>Identify yourself to the SMTP server using HELO. The hostname

25345

argument defaults to the fully qualified domain name of the local

25346

host.

25347

In normal operation it should not be necessary to call this method

25348

explicitly. It will be implicitly called by the sendmail()

25349

when necessary.</description>

25350

<param name="hostname" optional="0">hostname</param>

25351

<insert>helo(hostname)</insert><dialog title="Insert helo">helo(%0)</dialog><info title="Info window"></info></function>

25352

25353

25354

<description>Identify yourself to an ESMTP server using EHLO. The hostname

25355

argument defaults to the fully qualified domain name of the local

25356

host. Examine the response for ESMTP option and store them for use by

25357

has_extn().

25358

Unless you wish to use has_extn() before sending

25359

mail, it should not be necessary to call this method explicitly. It

25360

will be implicitly called by sendmail() when necessary.</description>

25361

<param name="hostname" optional="0">hostname</param>

25362

<insert>ehlo(hostname)</insert><dialog title="Insert ehlo">ehlo(%0)</dialog><info title="Info window"></info></function>

25363

25364

25365

<description>Return 1 if name is in the set of SMTP service extensions

25366

returned by the server, 0 otherwise. Case is ignored.</description>

25367

<param name="namename" optional="0">namename</param>

25368

<insert>has_extn(namename)</insert><dialog title="Insert has_extn">has_extn(%0)</dialog><info title="Info window"></info></function>

25369

25370

25371

<description>Check the validity of an address on this server using SMTP VRFY.

25372

Returns a tuple consisting of code 250 and a full 822 address

25373

(including human name) if the user address is valid. Otherwise returns

25374

an SMTP error code of 400 or greater and an error string.

25375

Many sites disable SMTP VRFY in order to foil spammers.</description>

25376

<param name="addressaddress" optional="0">addressaddress</param>

25377

<insert>verify(addressaddress)</insert><dialog title="Insert verify">verify(%0)</dialog><info title="Info window"></info></function>

25378

25379

25380

<description>Log in on an SMTP server that requires authentication.

25381

The arguments are the username and the password to authenticate with.

25382

If there has been no previous EHLO or HELO command this

25383

session, this method tries ESMTP EHLO first.

25384

This method will return normally if the authentication was successful,

25385

or may raise the following exceptions:

25386

[SMTPHeloError]

25387

The server didn't reply properly to the HELO greeting.

25388

[SMTPAuthenticationError]

25389

The server didn't accept the username/password combination.

25390

[SMTPError]

25391

No suitable authentication method was found.

25392

</description>

25393

<param name="user" optional="0">user</param><param name="password password" optional="0">password password</param>

25394

<insert>login(user, password password)</insert><dialog title="Insert login">login(%0, %1)</dialog><info title="Info window"></info></function>

25395

25396

25397

<description>Put the SMTP connection in TLS (Transport Layer Security) mode. All

25398

SMTP commands that follow will be encrypted. You should then call

25399

ehlo() again.

25400

If keyfile and certfile are provided, these are passed to

25401

the socket module's ssl() function.</description>

25402

<param name="keyfile" optional="0">keyfile</param><param name="certfile" optional="1">certfile</param>

25403

<insert>starttls(keyfile, [certfile])</insert><dialog title="Insert starttls">starttls(%0, %1)</dialog><info title="Info window"></info></function>

25404

25405

25406

<description>Send mail. The required arguments are an 822 from-address

25407

string, a list of 822 to-address strings, and a message string.

25408

The caller may pass a list of ESMTP options (such as 8bitmime)

25409

to be used in MAIL FROM commands as mail_options. ESMTP

25410

options (such as DSN commands) that should be used with all

25411

RCPT commands can be passed as rcpt_options. (If you

25412

need to use different ESMTP options to different recipients you have

25413

to use the low-level methods such as mail, rcpt and

25414

data to send the message.)

25415

The from_addr and to_addrs parameters are

25416

used to construct the message envelope used by the transport agents.

25417

The SMTP does not modify the message headers in any way.

25418

If there has been no previous EHLO or HELO command this

25419

session, this method tries ESMTP EHLO first. If the server does

25420

ESMTP, message size and each of the specified options will be passed

25421

to it (if the option is in the feature set the server advertises). If

25422

EHLO fails, HELO will be tried and ESMTP options

25423

suppressed.

25424

This method will return normally if the mail is accepted for at least

25425

one recipient. Otherwise it will throw an exception. That is, if this

25426

method does not throw an exception, then someone should get your mail.

25427

If this method does not throw an exception, it returns a dictionary,

25428

with one entry for each recipient that was refused. Each entry

25429

contains a tuple of the SMTP error code and the accompanying error

25430

message sent by the server.

25431

This method may raise the following exceptions:

25432

[SMTPRecipientsRefused]

25433

All recipients were refused. Nobody got the mail. The

25434

recipients attribute of the exception object is a dictionary

25435

with information about the refused recipients (like the one returned

25436

when at least one recipient was accepted).

25437

[SMTPHeloError]

25438

The server didn't reply properly to the HELO greeting.

25439

[SMTPSenderRefused]

25440

The server didn't accept the from_addr.

25441

[SMTPDataError]

25442

The server replied with an unexpected error code (other than a refusal

25443

of a recipient).

25444

Unless otherwise noted, the connection will be open even after

25445

an exception is raised.</description>

25446

<param name="from_addr" optional="0">from_addr</param><param name="to_addrs" optional="0">to_addrs</param><param name="msg" optional="0">msg</param><param name="mail_options" optional="1">mail_options</param><param name="rcpt_options" optional="1">rcpt_options</param>

25447

<insert>sendmail(from_addr, to_addrs, msg, [mail_options], [rcpt_options])</insert><dialog title="Insert sendmail">sendmail(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

25448

25449

25450

<description>Terminate the SMTP session and close the connection.</description>

25451

25452

25453

25454

</group>

25455

25456

</group>

25457

</group>

25458

25459

<description>Telnet client class.

25460

</description>

25461

25462

<description>Telnet represents a connection to a Telnet server. The

25463

instance is initially not connected by default; the open()

25464

method must be used to establish a connection. Alternatively, the

25465

host name and optional port number can be passed to the constructor,

25466

to, in which case the connection to the server will be established

25467

before the constructor returns.

25468

Do not reopen an already connected instance.

25469

This class has many read_*() methods. Note that some of them raise EOFError when the end of the connection is read,

25470

because they can return an empty string for other reasons. See the

25471

individual descriptions below.</description>

25472

25473

<insert>Telnet(host, [port])</insert><dialog title="Insert Telnet">Telnet(%0, %1)</dialog><info title="Info window"></info></function>

25474

25475

25476

<description>Telnet instances have the following methods:

25477

</description>

25478

25479

<description>Read until a given string, expected, is encountered or until

25480

timeout seconds have passed.

25481

When no match is found, return whatever is available instead,

25482

possibly the empty string. Raise EOFError if the connection

25483

is closed and no cooked data is available.</description>

25484

<param name="expected" optional="0">expected</param><param name="timeout" optional="1">timeout</param>

25485

<insert>read_until(expected, [timeout])</insert><dialog title="Insert read_until">read_until(%0, %1)</dialog><info title="Info window"></info></function>

25486

25487

25488

<description>Read all data until ; block until connection closed.</description>

25489

25490

25491

25492

25493

<description>Read at least one byte of cooked data unless is hit.

25494

Return '' if is hit. Block if no data is immediately

25495

available.</description>

25496

25497

25498

25499

25500

<description>Read everything that can be without blocking in I/O (eager).

25501

Raise EOFError if connection closed and no cooked data

25502

available. Return '' if no cooked data available otherwise.

25503

Do not block unless in the midst of an IAC sequence.</description>

25504

25505

<insert>read_very_eager()</insert><dialog title="Insert read_very_eager">read_very_eager()</dialog><info title="Info window"></info></function>

25506

25507

25508

<description>Read readily available data.

25509

Raise EOFError if connection closed and no cooked data

25510

available. Return '' if no cooked data available otherwise.

25511

Do not block unless in the midst of an IAC sequence.</description>

25512

25513

<insert>read_eager()</insert><dialog title="Insert read_eager">read_eager()</dialog><info title="Info window"></info></function>

25514

25515

25516

<description>Process and return data already in the queues (lazy).

25517

Raise EOFError if connection closed and no data available.

25518

Return '' if no cooked data available otherwise. Do not block

25519

unless in the midst of an IAC sequence.</description>

25520

25521

25522

25523

25524

<description>Return any data available in the cooked queue (very lazy).

25525

Raise EOFError if connection closed and no data available.

25526

Return '' if no cooked data available otherwise. This method

25527

never blocks.</description>

25528

25529

25530

25531

25532

<description>Return the data collected between a SB/SE pair (suboption begin/end).

25533

The callback should access these data when it was invoked with a

25534

SE command. This method never blocks.

25535

New in version 2.3</description>

25536

25537

25538

25539

25540

<description>Connect to a host.

25541

The optional second argument is the port number, which

25542

defaults to the standard Telnet port (23).

25543

Do not try to reopen an already connected instance.</description>

25544

25545

25546

25547

25548

<description>Print a debug message when the debug level is > 0.

25549

If extra arguments are present, they are substituted in the

25550

message using the standard string formatting operator.</description>

25551

25552

25553

25554

25555

<description>Set the debug level. The higher the value of debuglevel, the

25556

more debug output you get (on sys.stdout).</description>

25557

<param name="debugleveldebuglevel" optional="0">debugleveldebuglevel</param>

25558

<insert>set_debuglevel(debugleveldebuglevel)</insert><dialog title="Insert set_debuglevel">set_debuglevel(%0)</dialog><info title="Info window"></info></function>

25559

25560

25561

<description>Close the connection.</description>

25562

25563

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

25564

25565

25566

<description>Return the socket object used internally.</description>

25567

25568

<insert>get_socket()</insert><dialog title="Insert get_socket">get_socket()</dialog><info title="Info window"></info></function>

25569

25570

25571

<description>Return the file descriptor of the socket object used internally.</description>

25572

25573

<insert>fileno()</insert><dialog title="Insert fileno">fileno()</dialog><info title="Info window"></info></function>

25574

25575

25576

<description>Write a string to the socket, doubling any IAC characters.

25577

This can block if the connection is blocked. May raise

25578

socket.error if the connection is closed.</description>

25579

<param name="bufferbuffer" optional="0">bufferbuffer</param>

25580

<insert>write(bufferbuffer)</insert><dialog title="Insert write">write(%0)</dialog><info title="Info window"></info></function>

25581

25582

25583

<description>Interaction function, emulates a very dumb Telnet client.</description>

25584

25585

<insert>interact()</insert><dialog title="Insert interact">interact()</dialog><info title="Info window"></info></function>

25586

25587

25588

<description>Multithreaded version of interact().</description>

25589

25590

<insert>mt_interact()</insert><dialog title="Insert mt_interact">mt_interact()</dialog><info title="Info window"></info></function>

25591

25592

25593

<description>Read until one from a list of a regular expressions matches.

25594

The first argument is a list of regular expressions, either

25595

compiled (re.RegexObject instances) or uncompiled (strings).

25596

The optional second argument is a timeout, in seconds; the default

25597

is to block indefinitely.

25598

Return a tuple of three items: the index in the list of the

25599

first regular expression that matches; the match object

25600

returned; and the text read up till and including the match.

25601

If end of file is found and no text was read, raise

25602

EOFError. Otherwise, when nothing matches, return

25603

(-1, None, text) where text is the text received so

25604

far (may be the empty string if a timeout happened).

25605

If a regular expression ends with a greedy match (such as .*)

25606

or if more than one expression can match the same input, the

25607

results are indeterministic, and may depend on the I/O timing.</description>

25608

<param name="list" optional="0">list</param><param name="timeout" optional="1">timeout</param>

25609

<insert>expect(list, [timeout])</insert><dialog title="Insert expect">expect(%0, %1)</dialog><info title="Info window"></info></function>

25610

25611

25612

<description>Each time a telnet option is read on the input flow, this

25613

callback (if set) is called with the following parameters :

25614

callback(telnet socket, command (DO/DONT/WILL/WONT), option). No other

25615

action is done afterwards by telnetlib.</description>

25616

<param name="callbackcallback" optional="0">callbackcallback</param>

25617

<insert>set_option_negotiation_callback(callbackcallback)</insert><dialog title="Insert set_option_negotiation_callback">set_option_negotiation_callback(%0)</dialog><info title="Info window"></info></function>

25618

25619

</group>

25620

25621

</group>

25622

</group>

25623

25624

<description>Parse URLs into components.

25625

</description>

25626

25627

<description>Parse a URL into 6 components, returning a 6-tuple: (addressing

25628

scheme, network location, path, parameters, query, fragment

25629

identifier). This corresponds to the general structure of a URL:

25630

scheme://netloc/path;parameters?query#fragment.

25631

Each tuple item is a string, possibly empty.

25632

The components are not broken up in smaller parts (e.g. the network

25633

location is a single string), and % escapes are not expanded.

25634

The delimiters as shown above are not part of the tuple items,

25635

except for a leading slash in the path component, which is

25636

retained if present.

25637

Example:

25638

urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')

25639

yields the tuple

25640

('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')

25641

If the default_scheme argument is specified, it gives the

25642

default addressing scheme, to be used only if the URL string does not

25643

specify one. The default value for this argument is the empty string.

25644

If the allow_fragments argument is zero, fragment identifiers

25645

are not allowed, even if the URL's addressing scheme normally does

25646

support them. The default value for this argument is 1.</description>

25647

<param name="urlstring" optional="0">urlstring</param><param name="default_scheme" optional="1">default_scheme</param><param name="allow_fragments" optional="1">allow_fragments</param>

25648

<insert>urlparse(urlstring, [default_scheme], [allow_fragments])</insert><dialog title="Insert urlparse">urlparse(%0, %1, %2)</dialog><info title="Info window"></info></function>

25649

25650

25651

<description>Construct a URL string from a tuple as returned by urlparse().

25652

This may result in a slightly different, but equivalent URL, if the

25653

URL that was parsed originally had redundant delimiters, e.g. a ? with

25654

an empty query (the draft states that these are equivalent).</description>

25655

<param name="tupletuple" optional="0">tupletuple</param>

25656

<insert>urlunparse(tupletuple)</insert><dialog title="Insert urlunparse">urlunparse(%0)</dialog><info title="Info window"></info></function>

25657

25658

25659

<description>This is similar to urlparse(), but does not split the

25660

params from the URL. This should generally be used instead of

25661

urlparse() if the more recent URL syntax allowing

25662

parameters to be applied to each segment of the path portion of

25663

the URL (see 2396). A separate function is needed to separate

25664

the path segments and parameters. This function returns a 5-tuple:

25665

(addressing scheme, network location, path, query, fragment

25666

identifier).

25667

New in version 2.2</description>

25668

<param name="urlstring" optional="0">urlstring</param><param name="default_scheme" optional="1">default_scheme</param><param name="allow_fragments" optional="1">allow_fragments</param>

25669

<insert>urlsplit(urlstring, [default_scheme], [allow_fragments])</insert><dialog title="Insert urlsplit">urlsplit(%0, %1, %2)</dialog><info title="Info window"></info></function>

25670

25671

25672

<description>Combine the elements of a tuple as returned by urlsplit()

25673

into a complete URL as a string.

25674

New in version 2.2</description>

25675

<param name="tupletuple" optional="0">tupletuple</param>

25676

<insert>urlunsplit(tupletuple)</insert><dialog title="Insert urlunsplit">urlunsplit(%0)</dialog><info title="Info window"></info></function>

25677

25678

25679

<description>Construct a full (``absolute'') URL by combining a ``base URL''

25680

(base) with a ``relative URL'' (url). Informally, this

25681

uses components of the base URL, in particular the addressing scheme,

25682

the network location and (part of) the path, to provide missing

25683

components in the relative URL.

25684

Example:

25685

urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')

25686

yields the string

25687

'http://www.cwi.nl/%7Eguido/FAQ.html'

25688

The allow_fragments argument has the same meaning as for

25689

urlparse().</description>

25690

<param name="base" optional="0">base</param><param name="url" optional="0">url</param><param name="allow_fragments" optional="1">allow_fragments</param>

25691

<insert>urljoin(base, url, [allow_fragments])</insert><dialog title="Insert urljoin">urljoin(%0, %1, %2)</dialog><info title="Info window"></info></function>

25692

25693

25694

<description>If url contains a fragment identifier, returns a modified

25695

version of url with no fragment identifier, and the fragment

25696

identifier as a separate string. If there is no fragment identifier

25697

in url, returns url unmodified and an empty string.</description>

25698

<param name="urlurl" optional="0">urlurl</param>

25699

<insert>urldefrag(urlurl)</insert><dialog title="Insert urldefrag">urldefrag(%0)</dialog><info title="Info window"></info></function>

25700

25701

</group>

25702

25703

<description>A framework for network servers.

25704

The SocketServer module simplifies the task of writing network

25705

servers.

25706

There are four basic server classes: TCPServer uses the

25707

Internet TCP protocol, which provides for continuous streams of data

25708

between the client and server. UDPServer uses datagrams, which

25709

are discrete packets of information that may arrive out of order or be

25710

lost while in transit. The more infrequently used

25711

UnixStreamServer and UnixDatagramServer classes are

25712

similar, but use domain sockets; they're not available on

25713

non- platforms. For more details on network programming, consult

25714

a book such as W. Richard Steven's UNIX Network Programming

25715

or Ralph Davis's Win32 Network Programming.

25716

These four classes process requests synchronously; each request

25717

must be completed before the next request can be started. This isn't

25718

suitable if each request takes a long time to complete, because it

25719

requires a lot of computation, or because it returns a lot of data

25720

which the client is slow to process. The solution is to create a

25721

separate process or thread to handle each request; the

25722

ForkingMixIn and ThreadingMixIn mix-in classes can be

25723

used to support asynchronous behaviour.

25724

Creating a server requires several steps. First, you must create a

25725

request handler class by subclassing the BaseRequestHandler

25726

class and overriding its handle() method; this method will

25727

process incoming requests. Second, you must instantiate one of the

25728

server classes, passing it the server's address and the request

25729

handler class. Finally, call the handle_request() or

25730

serve_forever() method of the server object to process one or

25731

many requests.

25732

When inheriting from ThreadingMixIn for threaded connection

25733

behavior, you should explicitly declare how you want your threads

25734

to behave on an abrupt shutdown. The ThreadingMixIn class

25735

defines an attribute daemon_threads, which indicates whether

25736

or not the server should wait for thread termination. You should

25737

set the flag explicitly if you would like threads to behave

25738

autonomously; the default is False, meaning that Python

25739

will not exit until all threads created by ThreadingMixIn have

25740

exited.

25741

Server classes have the same external methods and attributes, no

25742

matter what network protocol they use:

25743

</description>

25744

25745

<description>Return an integer file descriptor for the socket on which the server

25746

is listening. This function is most commonly passed to

25747

select.select(), to allow monitoring multiple servers in the

25748

same process.</description>

25749

25750

<insert>fileno()</insert><dialog title="Insert fileno">fileno()</dialog><info title="Info window"></info></function>

25751

25752

25753

<description>Process a single request. This function calls the following methods

25754

in order: get_request(), verify_request(), and

25755

process_request(). If the user-provided handle()

25756

method of the handler class raises an exception, the server's

25757

handle_error() method will be called.</description>

25758

25759

<insert>handle_request()</insert><dialog title="Insert handle_request">handle_request()</dialog><info title="Info window"></info></function>

25760

25761

25762

<description>Handle an infinite number of requests. This simply calls

25763

handle_request() inside an infinite loop.</description>

25764

25765

<insert>serve_forever()</insert><dialog title="Insert serve_forever">serve_forever()</dialog><info title="Info window"></info></function>

25766

25767

25768

<description>Actually processes the request by instantiating

25769

RequestHandlerClass and calling its handle() method.</description>

25770

25771

<insert>finish_request()</insert><dialog title="Insert finish_request">finish_request()</dialog><info title="Info window"></info></function>

25772

25773

25774

<description>Must accept a request from the socket, and return a 2-tuple containing

25775

the new socket object to be used to communicate with the

25776

client, and the client's address.</description>

25777

25778

<insert>get_request()</insert><dialog title="Insert get_request">get_request()</dialog><info title="Info window"></info></function>

25779

25780

25781

<description>This function is called if the RequestHandlerClass's

25782

handle() method raises an exception. The default action is

25783

to print the traceback to standard output and continue handling

25784

further requests.</description>

25785

<param name="request" optional="0">request</param><param name="client_address client_address" optional="0">client_address client_address</param>

25786

<insert>handle_error(request, client_address client_address)</insert><dialog title="Insert handle_error">handle_error(%0, %1)</dialog><info title="Info window"></info></function>

25787

25788

25789

<description>Calls finish_request() to create an instance of the

25790

RequestHandlerClass. If desired, this function can create a

25791

new process or thread to handle the request; the ForkingMixIn

25792

and ThreadingMixIn classes do this.</description>

25793

<param name="request" optional="0">request</param><param name="client_address client_address" optional="0">client_address client_address</param>

25794

<insert>process_request(request, client_address client_address)</insert><dialog title="Insert process_request">process_request(%0, %1)</dialog><info title="Info window"></info></function>

25795

25796

25797

<description>Called by the server's constructor to activate the server.

25798

May be overridden.</description>

25799

25800

<insert>server_activate()</insert><dialog title="Insert server_activate">server_activate()</dialog><info title="Info window"></info></function>

25801

25802

25803

<description>Called by the server's constructor to bind the socket to the desired

25804

address. May be overridden.</description>

25805

25806

<insert>server_bind()</insert><dialog title="Insert server_bind">server_bind()</dialog><info title="Info window"></info></function>

25807

25808

25809

<description>Must return a Boolean value; if the value is true, the request will be

25810

processed, and if it's false, the request will be denied.

25811

This function can be overridden to implement access controls for a server.

25812

The default implementation always return true.</description>

25813

<param name="request" optional="0">request</param><param name="client_address client_address" optional="0">client_address client_address</param>

25814

<insert>verify_request(request, client_address client_address)</insert><dialog title="Insert verify_request">verify_request(%0, %1)</dialog><info title="Info window"></info></function>

25815

25816

25817

<description>Called after the handle() method to perform any clean-up

25818

actions required. The default implementation does nothing. If

25819

setup() or handle() raise an exception, this

25820

function will not be called.</description>

25821

25822

<insert>finish()</insert><dialog title="Insert finish">finish()</dialog><info title="Info window"></info></function>

25823

25824

25825

<description>This function must do all the work required to service a request.

25826

Several instance attributes are available to it; the request is

25827

available as self.request; the client address as

25828

self.client_address; and the server instance as

25829

self.server, in case it needs access to per-server

25830

information.

25831

The type of self.request is different for datagram or stream

25832

services. For stream services, self.request is a socket

25833

object; for datagram services, self.request is a string.

25834

However, this can be hidden by using the mix-in request handler

25835

classes

25836

StreamRequestHandler or DatagramRequestHandler, which

25837

override the setup() and finish() methods, and

25838

provides self.rfile and self.wfile attributes.

25839

self.rfile and self.wfile can be read or written,

25840

respectively, to get the request data or return data to the client.</description>

25841

25842

<insert>handle()</insert><dialog title="Insert handle">handle()</dialog><info title="Info window"></info></function>

25843

25844

25845

<description>Called before the handle() method to perform any

25846

initialization actions required. The default implementation does

25847

nothing.</description>

25848

25849

<insert>setup()</insert><dialog title="Insert setup">setup()</dialog><info title="Info window"></info></function>

25850

25851

</group>

25852

25853

<description>Basic HTTP server (base class for

25854

SimpleHTTPServer and CGIHTTPServer).

25855

</description>

25856

25857

<description>This class builds on the TCPServer class by

25858

storing the server address as instance

25859

variables named server_name and server_port. The

25860

server is accessible by the handler, typically through the handler's

25861

server instance variable.</description>

25862

<param name="server_address" optional="0">server_address</param><param name="RequestHandlerClass RequestHandlerClass" optional="0">RequestHandlerClass RequestHandlerClass</param>

25863

<insert>HTTPServer(server_address, RequestHandlerClass RequestHandlerClass)</insert><dialog title="Insert HTTPServer">HTTPServer(%0, %1)</dialog><info title="Info window"></info></function>

25864

25865

25866

<description>This class is used

25867

to handle the HTTP requests that arrive at the server. By itself,

25868

it cannot respond to any actual HTTP requests; it must be subclassed

25869

to handle each request method (e.g. GET or POST).

25870

BaseHTTPRequestHandler provides a number of class and instance

25871

variables, and methods for use by subclasses.

25872

The handler will parse the request and the headers, then call a

25873

method specific to the request type. The method name is constructed

25874

from the request. For example, for the request method SPAM, the

25875

do_SPAM() method will be called with no arguments. All of

25876

the relevant information is stored in instance variables of the

25877

handler. Subclasses should not need to override or extend the

25878

__init__() method.</description>

25879

<param name="request" optional="0">request</param><param name="client_address" optional="0">client_address</param><param name="server server" optional="0">server server</param>

25880

<insert>BaseHTTPRequestHandler(request, client_address, server server)</insert><dialog title="Insert BaseHTTPRequestHandler">BaseHTTPRequestHandler(%0, %1, %2)</dialog><info title="Info window"></info></function>

25881

25882

25883

<description>Calls handle_one_request() once (or, if persistent connections

25884

are enabled, multiple times) to handle incoming HTTP requests.

25885

You should never need to override it; instead, implement appropriate

25886

do_*() methods.</description>

25887

25888

<insert>handle()</insert><dialog title="Insert handle">handle()</dialog><info title="Info window"></info></function>

25889

25890

25891

<description>This method will parse and dispatch

25892

the request to the appropriate do_*() method. You should

25893

never need to override it.</description>

25894

25895

<insert>handle_one_request()</insert><dialog title="Insert handle_one_request">handle_one_request()</dialog><info title="Info window"></info></function>

25896

25897

25898

<description>Sends and logs a complete error reply to the client. The numeric

25899

code specifies the HTTP error code, with message as

25900

optional, more specific text. A complete set of headers is sent,

25901

followed by text composed using the error_message_format

25902

class variable.</description>

25903

<param name="code" optional="0">code</param><param name="message" optional="1">message</param>

25904

<insert>send_error(code, [message])</insert><dialog title="Insert send_error">send_error(%0, %1)</dialog><info title="Info window"></info></function>

25905

25906

25907

<description>Sends a response header and logs the accepted request. The HTTP

25908

response line is sent, followed by Server and Date

25909

headers. The values for these two headers are picked up from the

25910

version_string() and date_time_string() methods,

25911

respectively.</description>

25912

<param name="code" optional="0">code</param><param name="message" optional="1">message</param>

25913

<insert>send_response(code, [message])</insert><dialog title="Insert send_response">send_response(%0, %1)</dialog><info title="Info window"></info></function>

25914

25915

25916

<description>Writes a specific MIME header to the output stream. keyword

25917

should specify the header keyword, with value specifying

25918

its value.</description>

25919

<param name="keyword" optional="0">keyword</param><param name="value value" optional="0">value value</param>

25920

<insert>send_header(keyword, value value)</insert><dialog title="Insert send_header">send_header(%0, %1)</dialog><info title="Info window"></info></function>

25921

25922

25923

<description>Sends a blank line, indicating the end of the MIME headers in

25924

the response.</description>

25925

25926

<insert>end_headers()</insert><dialog title="Insert end_headers">end_headers()</dialog><info title="Info window"></info></function>

25927

25928

25929

<description>Logs an accepted (successful) request. code should specify

25930

the numeric HTTP code associated with the response. If a size of

25931

the response is available, then it should be passed as the

25932

size parameter.</description>

25933

25934

<insert>log_request(code, [size])</insert><dialog title="Insert log_request">log_request(%0, %1)</dialog><info title="Info window"></info></function>

25935

25936

25937

<description>Logs an error when a request cannot be fulfilled. By default,

25938

it passes the message to log_message(), so it takes the

25939

same arguments (format and additional values).</description>

25940

25941

<insert>log_error(......)</insert><dialog title="Insert log_error">log_error(%0)</dialog><info title="Info window"></info></function>

25942

25943

25944

<description>Logs an arbitrary message to sys.stderr. This is typically

25945

overridden to create custom error logging mechanisms. The

25946

format argument is a standard printf-style format string,

25947

where the additional arguments to log_message() are applied

25948

as inputs to the formatting. The client address and current date

25949

and time are prefixed to every message logged.</description>

25950

<param name="format" optional="0">format</param><param name="... ..." optional="0">... ...</param>

25951

<insert>log_message(format, ... ...)</insert><dialog title="Insert log_message">log_message(%0, %1)</dialog><info title="Info window"></info></function>

25952

25953

25954

<description>Returns the server software's version string. This is a combination

25955

of the server_version and sys_version class variables.</description>

25956

25957

<insert>version_string()</insert><dialog title="Insert version_string">version_string()</dialog><info title="Info window"></info></function>

25958

25959

25960

<description>Returns the current date and time, formatted for a message header.</description>

25961

25962

<insert>date_time_string()</insert><dialog title="Insert date_time_string">date_time_string()</dialog><info title="Info window"></info></function>

25963

25964

25965

<description>Returns the current date and time, formatted for logging.</description>

25966

25967

<insert>log_data_time_string()</insert><dialog title="Insert log_data_time_string">log_data_time_string()</dialog><info title="Info window"></info></function>

25968

25969

25970

<description>Returns the client address, formatted for logging. A name lookup

25971

is performed on the client's IP address.</description>

25972

25973

<insert>address_string()</insert><dialog title="Insert address_string">address_string()</dialog><info title="Info window"></info></function>

25974

25975

</group>

25976

25977

<description>This module provides a basic request handler for HTTP

25978

servers.

25979

The SimpleHTTPServer module defines a request-handler class,

25980

interface compatible with BaseHTTPServer.BaseHTTPRequestHandler

25981

which serves files only from a base directory.

25982

The SimpleHTTPServer module defines the following class:

25983

</description>

25984

25985

<description>This class is used, to serve files from current directory and below,

25986

directly mapping the directory structure to HTTP requests.

25987

A lot of the work is done by the base class

25988

BaseHTTPServer.BaseHTTPRequestHandler, such as parsing the

25989

request. This class implements the do_GET() and

25990

do_HEAD() functions.</description>

25991

<param name="request" optional="0">request</param><param name="client_address" optional="0">client_address</param><param name="server server" optional="0">server server</param>

25992

<insert>SimpleHTTPRequestHandler(request, client_address, server server)</insert><dialog title="Insert SimpleHTTPRequestHandler">SimpleHTTPRequestHandler(%0, %1, %2)</dialog><info title="Info window"></info></function>

25993

25994

25995

<description>This method serves the 'HEAD' request type: it sends the

25996

headers it would send for the equivalent GET request. See the

25997

do_GET() method for more complete explanation of the possible

25998

headers.</description>

25999

26000

26001

26002

26003

<description>The request is mapped to a local file by interpreting the request as

26004

a path relative to the current working directory.

26005

If the request was mapped to a directory, a 403 respond is output,

26006

followed by the explanation 'Directory listing not supported'.

26007

Any IOError exception in opening the requested file, is mapped

26008

to a 404, 'File not found' error. Otherwise, the content

26009

type is guessed using the extensions_map variable.

26010

A 'Content-type:' with the guessed content type is output, and

26011

then a blank line, signifying end of headers, and then the contents of

26012

the file. The file is always opened in binary mode.

26013

For example usage, see the implementation of the test()

26014

function.</description>

26015

26016

26017

26018

</group>

26019

26020

<description>This module provides a request handler for HTTP servers

26021

which can run CGI scripts.

26022

The CGIHTTPServer module defines a request-handler class,

26023

interface compatible with

26024

BaseHTTPServer.BaseHTTPRequestHandler and inherits behavior

26025

from SimpleHTTPServer.SimpleHTTPRequestHandler but can also

26026

run CGI scripts.

26027

This module can run CGI scripts on and Windows systems;

26028

on Mac OS it will only be able to run Python scripts within the same

26029

process as itself.

26030

The CGIHTTPServer module defines the following class:

26031

</description>

26032

26033

<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

26034

structure to local directory structure is exactly as in

26035

SimpleHTTPServer.SimpleHTTPRequestHandler.

26036

The class will however, run the CGI script, instead of serving it as a

26037

file, if it guesses it to be a CGI script. Only directory-based CGI

26038

are used --- the other common server configuration is to treat special

26039

extensions as denoting CGI scripts.

26040

The do_GET() and do_HEAD() functions are

26041

modified to run CGI scripts and serve the output, instead of serving

26042

files, if the request leads to somewhere below the

26043

cgi_directories path.</description>

26044

<param name="request" optional="0">request</param><param name="client_address" optional="0">client_address</param><param name="server server" optional="0">server server</param>

26045

<insert>CGIHTTPRequestHandler(request, client_address, server server)</insert><dialog title="Insert CGIHTTPRequestHandler">CGIHTTPRequestHandler(%0, %1, %2)</dialog><info title="Info window"></info></function>

26046

26047

26048

<description>This method serves the 'POST' request type, only allowed for

26049

CGI scripts. Error 501, "Can only POST to CGI scripts", is output

26050

when trying to POST to a non-CGI url.</description>

26051

26052

26053

26054

</group>

26055

26056

<description>Support for HTTP state management (cookies).

26057

The Cookie module defines classes for abstracting the concept of cookies, an HTTP state management mechanism. It supports both simple

26058

string-only cookies, and provides an abstraction for having any serializable

26059

data-type as cookie value.

26060

The module formerly strictly applied the parsing rules described in

26061

the 2109 and 2068 specifications. It has since been discovered

26062

that MSIE 3.0x doesn't follow the character rules outlined in those

26063

specs. As a result, the parsing rules used are a bit less strict.

26064

{CookieError}

26065

Exception failing because of 2109 invalidity: incorrect

26066

attributes, incorrect Set-Cookie header, etc.

26067

</description>

26068

26069

<description>This class is a dictionary-like object whose keys are strings and

26070

whose values are Morsel instances. Note that upon setting a key to

26071

a value, the value is first converted to a Morsel containing

26072

the key and the value.

26073

If input is given, it is passed to the load() method.</description>

26074

<param name="input" optional="0">input</param>

26075

<insert>BaseCookie(input)</insert><dialog title="Insert BaseCookie">BaseCookie(%0)</dialog><info title="Info window"></info></function>

26076

26077

26078

<description>This class derives from BaseCookie and overrides

26079

value_decode() and value_encode() to be the identity

26080

and str() respectively.</description>

26081

<param name="input" optional="0">input</param>

26082

<insert>SimpleCookie(input)</insert><dialog title="Insert SimpleCookie">SimpleCookie(%0)</dialog><info title="Info window"></info></function>

26083

26084

26085

<description>This class derives from BaseCookie and overrides

26086

value_decode() and value_encode() to be the

26087

pickle.loads() and pickle.dumps().

26088

2.3{Reading pickled values from untrusted

26089

cookie data is a huge security hole, as pickle strings can be crafted

26090

to cause arbitrary code to execute on your server. It is supported

26091

for backwards compatibility only, and may eventually go away.}</description>

26092

<param name="input" optional="0">input</param>

26093

<insert>SerialCookie(input)</insert><dialog title="Insert SerialCookie">SerialCookie(%0)</dialog><info title="Info window"></info></function>

26094

26095

26096

<description>This class derives from BaseCookie. It overrides

26097

value_decode() to be pickle.loads() if it is a

26098

valid pickle, and otherwise the value itself. It overrides

26099

value_encode() to be pickle.dumps() unless it is a

26100

string, in which case it returns the value itself.

26101

2.3{The same security warning from SerialCookie

26102

applies here.}</description>

26103

<param name="input" optional="0">input</param>

26104

<insert>SmartCookie(input)</insert><dialog title="Insert SmartCookie">SmartCookie(%0)</dialog><info title="Info window"></info></function>

26105

26106

26107

26108

<description>Return a decoded value from a string representation. Return value can

26109

be any type. This method does nothing in BaseCookie --- it exists

26110

so it can be overridden.</description>

26111

<param name="valval" optional="0">valval</param>

26112

<insert>value_decode(valval)</insert><dialog title="Insert value_decode">value_decode(%0)</dialog><info title="Info window"></info></function>

26113

26114

26115

<description>Return an encoded value. val can be any type, but return value

26116

must be a string. This method does nothing in BaseCookie --- it exists

26117

so it can be overridden

26118

In general, it should be the case that value_encode() and value_decode() are inverses on the range of value_decode.</description>

26119

<param name="valval" optional="0">valval</param>

26120

<insert>value_encode(valval)</insert><dialog title="Insert value_encode">value_encode(%0)</dialog><info title="Info window"></info></function>

26121

26122

26123

<description>Return a string representation suitable to be sent as HTTP headers.

26124

attrs and header are sent to each Morsel's

26125

output() method. sep is used to join the headers

26126

together, and is by default a newline.</description>

26127

<param name="attrs" optional="0">attrs</param><param name="header" optional="1">header</param><param name="sep" optional="1">sep</param>

26128

<insert>output(attrs, [header], [sep])</insert><dialog title="Insert output">output(%0, %1, %2)</dialog><info title="Info window"></info></function>

26129

26130

26131

<description>Return an embeddable JavaScript snippet, which, if run on a browser which

26132

supports JavaScript, will act the same as if the HTTP headers was sent.

26133

The meaning for attrs is the same as in output().</description>

26134

<param name="attrs" optional="0">attrs</param>

26135

<insert>js_output(attrs)</insert><dialog title="Insert js_output">js_output(%0)</dialog><info title="Info window"></info></function>

26136

26137

26138

<description>If rawdata is a string, parse it as an HTTP_COOKIE and add

26139

the values found there as Morsels. If it is a dictionary, it

26140

is equivalent to:

26141

for k, v in rawdata.items():

26142

cookie[k] = v

26143

</description>

26144

<param name="rawdatarawdata" optional="0">rawdatarawdata</param>

26145

<insert>load(rawdatarawdata)</insert><dialog title="Insert load">load(%0)</dialog><info title="Info window"></info></function>

26146

26147

</group>

26148

26149

26150

<description>Abstract a key/value pair, which has some 2109 attributes.

26151

Morsels are dictionary-like objects, whose set of keys is constant ---

26152

the valid 2109 attributes, which are

26153

expires

26154

path

26155

comment

26156

domain

26157

max-age

26158

secure

26159

version

26160

The keys are case-insensitive.</description>

26161

26162

<insert>Morsel()</insert><dialog title="Insert Morsel">Morsel()</dialog><info title="Info window"></info></function>

26163

26164

26165

<description>Set the key, value and coded_value members.</description>

26166

<param name="key" optional="0">key</param><param name="value" optional="0">value</param><param name="coded_value coded_value" optional="0">coded_value coded_value</param>

26167

<insert>set(key, value, coded_value coded_value)</insert><dialog title="Insert set">set(%0, %1, %2)</dialog><info title="Info window"></info></function>

26168

26169

26170

<description>Whether K is a member of the set of keys of a Morsel.</description>

26171

26172

<insert>isReservedKey(KK)</insert><dialog title="Insert isReservedKey">isReservedKey(%0)</dialog><info title="Info window"></info></function>

26173

26174

26175

<description>Return a string representation of the Morsel, suitable

26176

to be sent as an HTTP header. By default, all the attributes are included,

26177

unless attrs is given, in which case it should be a list of attributes

26178

to use. header is by default "Set-Cookie:".</description>

26179

<param name="attrs" optional="0">attrs</param><param name="header" optional="1">header</param>

26180

<insert>output(attrs, [header])</insert><dialog title="Insert output">output(%0, %1)</dialog><info title="Info window"></info></function>

26181

26182

26183

<description>Return an embeddable JavaScript snippet, which, if run on a browser which

26184

supports JavaScript, will act the same as if the HTTP header was sent.

26185

The meaning for attrs is the same as in output().</description>

26186

<param name="attrs" optional="0">attrs</param>

26187

<insert>js_output(attrs)</insert><dialog title="Insert js_output">js_output(%0)</dialog><info title="Info window"></info></function>

26188

26189

26190

<description>Return a string representing the Morsel, without any surrounding HTTP

26191

or JavaScript.

26192

The meaning for attrs is the same as in output().</description>

26193

<param name="attrs" optional="0">attrs</param>

26194

<insert>OutputString(attrs)</insert><dialog title="Insert OutputString">OutputString(%0)</dialog><info title="Info window"></info></function>

26195

26196

</group>

26197

26198

</group>

26199

</group>

26200

26201

<description>XML-RPC client access.

26202

% Not everyting is documented yet. It might be good to describe % Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.

26203

New in version 2.2

26204

XML-RPC is a Remote Procedure Call method that uses XML passed via

26205

HTTP as a transport. With it, a client can call methods with

26206

parameters on a remote server (the server is named by a URI) and get back

26207

structured data. This module supports writing XML-RPC client code; it

26208

handles all the details of translating between conformable Python

26209

objects and XML on the wire.

26210

</description>

26211

26212

<description>A ServerProxy instance is an object that manages communication

26213

with a remote XML-RPC server. The required first argument is a URI

26214

(Uniform Resource Indicator), and will normally be the URL of the

26215

server. The optional second argument is a transport factory instance;

26216

by default it is an internal SafeTransport instance for https:

26217

URLs and an internal HTTP Transport instance otherwise. The

26218

optional third argument is an encoding, by default UTF-8. The optional

26219

fourth argument is a debugging flag. If allow_none is true, the Python constant None will be translated into XML; the

26220

default behaviour is for None to raise a TypeError.

26221

This is a commonly-used extension to the XML-RPC specification, but isn't

26222

supported by all clients and servers; see

26223

http://ontosys.com/xml-rpc/extensions.html for a description. Both the HTTP and HTTPS transports support the URL syntax extension for

26224

HTTP Basic Authentication: http://user:pass@host:port/path. The user:pass portion will be base64-encoded as an HTTP `Authorization'

26225

header, and sent to the remote server as part of the connection process

26226

when invoking an XML-RPC method. You only need to use this if the

26227

remote server requires a Basic Authentication user and password.

26228

The returned instance is a proxy object with methods that can be used

26229

to invoke corresponding RPC calls on the remote server. If the remote

26230

server supports the introspection API, the proxy can also be used to query

26231

the remote server for the methods it supports (service discovery) and

26232

fetch other server-associated metadata.

26233

ServerProxy instance methods take Python basic types and objects as arguments and return Python basic types and classes. Types that are

26234

conformable (e.g. that can be marshalled through XML), include the

26235

following (and except where noted, they are unmarshalled as the same

26236

Python type):

26237

{l|l}{constant}{Name}{Meaning}

26238

boolean{The True and False constants}

26239

integers{Pass in directly}

26240

floating-point numbers{Pass in directly}

26241

strings{Pass in directly}

26242

arrays{Any Python sequence type containing conformable

26243

elements. Arrays are returned as lists}

26244

structures{A Python dictionary. Keys must be strings,

26245

values may be any conformable type.}

26246

dates{in seconds since the epoch; pass in an instance of the

26247

DateTime wrapper class}

26248

binary data{pass in an instance of the Binary

26249

wrapper class}

26250

This is the full set of data types supported by XML-RPC. Method calls

26251

may also raise a special Fault instance, used to signal

26252

XML-RPC server errors, or ProtocolError used to signal an

26253

error in the HTTP/HTTPS transport layer. Note that even though starting

26254

with Python 2.2 you can subclass builtin types, the xmlrpclib module

26255

currently does not marshal instances of such subclasses.

26256

When passing strings, characters special to XML such as <,

26257

>, and & will be automatically escaped. However, it's

26258

the caller's responsibility to ensure that the string is free of

26259

characters that aren't allowed in XML, such as the control characters

26260

with ASCII values between 0 and 31; failing to do this will result in

26261

an XML-RPC request that isn't well-formed XML. If you have to pass

26262

arbitrary strings via XML-RPC, use the Binary wrapper class

26263

described below.

26264

Server is retained as an alias for ServerProxy for backwards

26265

compatibility. New code should use ServerProxy.</description>

26266

<param name="uri" optional="0">uri</param><param name="transport" optional="1">transport</param><param name="encoding" optional="1">encoding</param><param name="verbose" optional="1">verbose</param><param name="allow_none" optional="1">allow_none</param>

26267

<insert>ServerProxy(uri, [transport], [encoding], [verbose], [allow_none])</insert><dialog title="Insert ServerProxy">ServerProxy(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

26268

26269

26270

<description>A ServerProxy instance has a method corresponding to

26271

each remote procedure call accepted by the XML-RPC server. Calling

26272

the method performs an RPC, dispatched by both name and argument

26273

signature (e.g. the same method name can be overloaded with multiple

26274

argument signatures). The RPC finishes by returning a value, which

26275

may be either returned data in a conformant type or a Fault or

26276

ProtocolError object indicating an error.

26277

Servers that support the XML introspection API support some common

26278

methods grouped under the reserved system member:

26279

</description>

26280

26281

<description>This method returns a list of strings, one for each (non-system)

26282

method supported by the XML-RPC server.</description>

26283

26284

<insert>system.listMethods()</insert><dialog title="Insert system.listMethods">system.listMethods()</dialog><info title="Info window"></info></function>

26285

26286

26287

<description>This method takes one parameter, the name of a method implemented by

26288

the XML-RPC server.It returns an array of possible signatures for this

26289

method. A signature is an array of types. The first of these types is

26290

the return type of the method, the rest are parameters.

26291

Because multiple signatures (ie. overloading) is permitted, this method

26292

returns a list of signatures rather than a singleton.

26293

Signatures themselves are restricted to the top level parameters

26294

expected by a method. For instance if a method expects one array of

26295

structs as a parameter, and it returns a string, its signature is

26296

simply "string, array". If it expects three integers and returns a

26297

string, its signature is "string, int, int, int".

26298

If no signature is defined for the method, a non-array value is

26299

returned. In Python this means that the type of the returned value will be something other that list.</description>

26300

<param name="namename" optional="0">namename</param>

26301

<insert>system.methodSignature(namename)</insert><dialog title="Insert system.methodSignature">system.methodSignature(%0)</dialog><info title="Info window"></info></function>

26302

26303

26304

<description>This method takes one parameter, the name of a method implemented by

26305

the XML-RPC server. It returns a documentation string describing the

26306

use of that method. If no such string is available, an empty string is

26307

returned. The documentation string may contain HTML markup.</description>

26308

<param name="namename" optional="0">namename</param>

26309

<insert>system.methodHelp(namename)</insert><dialog title="Insert system.methodHelp">system.methodHelp(%0)</dialog><info title="Info window"></info></function>

26310

26311

</group>

26312

26313

<description>This class may be initialized from any Python value; the instance

26314

returned depends only on its truth value. It supports various Python

26315

operators through __cmp__(), __repr__(),

26316

__int__(), and __nonzero__() methods, all

26317

implemented in the obvious ways.

26318

It also has the following method, supported mainly for internal use by

26319

the unmarshalling code:

26320

</description>

26321

26322

<description>Write the XML-RPC encoding of this Boolean item to the out stream object.</description>

26323

<param name="outout" optional="0">outout</param>

26324

<insert>encode(outout)</insert><dialog title="Insert encode">encode(%0)</dialog><info title="Info window"></info></function>

26325

26326

</group>

26327

26328

<description>This class may initialized from date in seconds since the epoch, a

26329

time tuple, or an ISO 8601 time/date string. It has the following

26330

methods, supported mainly for internal use by the

26331

marshalling/unmarshalling code:

26332

</description>

26333

26334

<description>Accept a string as the instance's new time value.</description>

26335

<param name="stringstring" optional="0">stringstring</param>

26336

<insert>decode(stringstring)</insert><dialog title="Insert decode">decode(%0)</dialog><info title="Info window"></info></function>

26337

26338

26339

<description>Write the XML-RPC encoding of this DateTime item to the out stream object.</description>

26340

<param name="outout" optional="0">outout</param>

26341

<insert>encode(outout)</insert><dialog title="Insert encode">encode(%0)</dialog><info title="Info window"></info></function>

26342

26343

</group>

26344

26345

<description>This class may initialized from string data (which may include NULs).

26346

The primary acess to the content of a Binary object is

26347

provided by an attribute:

26348

[Binary]{data}

26349

The binary data encapsulated by the Binary instance. The data

26350

is provided as an 8-bit string.

26351

Binary objects have the following methods, supported mainly

26352

for internal use by the marshalling/unmarshalling code:

26353

</description>

26354

26355

<description>Accept a base64 string and decode it as the instance's new data.</description>

26356

<param name="stringstring" optional="0">stringstring</param>

26357

<insert>decode(stringstring)</insert><dialog title="Insert decode">decode(%0)</dialog><info title="Info window"></info></function>

26358

26359

26360

<description>Write the XML-RPC base 64 encoding of this binary item to the out

26361

stream object.</description>

26362

<param name="outout" optional="0">outout</param>

26363

<insert>encode(outout)</insert><dialog title="Insert encode">encode(%0)</dialog><info title="Info window"></info></function>

26364

26365

</group>

26366

26367

<description>A Fault object encapsulates the content of an XML-RPC fault tag.

26368

Fault objects have the following members:

26369

{faultCode}

26370

A string indicating the fault type.

26371

{faultString}

26372

A string containing a diagnostic message associated with the fault.

26373

</description>

26374

</group>

26375

26376

<description>A ProtocolError object describes a protocol error in the

26377

underlying transport layer (such as a 404 `not found' error if the

26378

server named by the URI does not exist). It has the following

26379

members:

26380

{url}

26381

The URI or URL that triggered the error.

26382

{errcode}

26383

The error code.

26384

{errmsg}

26385

The error message or diagnostic string.

26386

{headers}

26387

A string containing the headers of the HTTP/HTTPS request that

26388

triggered the error.

26389

</description>

26390

</group>

26391

26392

<description>New in version 2.4

26393

In http://www.xmlrpc.com/discuss/msgReader8, an approach

26394

is presented to encapsulate multiple calls to a remote server into

26395

a single request.

26396

</description>

26397

26398

<description>Create an object used to boxcar method calls. server is the

26399

eventual target of the call. Calls can be made to the result object,

26400

but they will immediately return None, and only store the

26401

call name and parameters in the MultiCall object. Calling

26402

the object itself causes all stored calls to be transmitted as

26403

a single system.multicall request. The result of this call

26404

is a generator; iterating over this generator yields the individual

26405

results.</description>

26406

<param name="serverserver" optional="0">serverserver</param>

26407

<insert>MultiCall(serverserver)</insert><dialog title="Insert MultiCall">MultiCall(%0)</dialog><info title="Info window"></info></function>

26408

26409

</group>

26410

26411

26412

<description>Convert any Python value to one of the XML-RPC Boolean constants,

26413

True or False.</description>

26414

<param name="valuevalue" optional="0">valuevalue</param>

26415

<insert>boolean(valuevalue)</insert><dialog title="Insert boolean">boolean(%0)</dialog><info title="Info window"></info></function>

26416

26417

26418

<description>Trivially convert any Python string to a Binary object.</description>

26419

<param name="datadata" optional="0">datadata</param>

26420

<insert>binary(datadata)</insert><dialog title="Insert binary">binary(%0)</dialog><info title="Info window"></info></function>

26421

26422

26423

<description>Convert params into an XML-RPC request.

26424

or into a response if methodresponse is true.

26425

params can be either a tuple of arguments or an instance of the Fault exception class. If methodresponse is true,

26426

only a single value can be returned, meaning that params must be of length 1.

26427

encoding, if supplied, is the encoding to use in the generated

26428

XML; the default is UTF-8. Python's None value cannot be

26429

used in standard XML-RPC; to allow using it via an extension, provide a true value for allow_none.</description>

26430

<param name="params" optional="0">params</param><param name="methodname" optional="1">methodname</param><param name="methodresponse" optional="1">methodresponse</param><param name="encoding" optional="1">encoding</param><param name="allow_none" optional="1">allow_none</param>

26431

<insert>dumps(params, [methodname], [methodresponse], [encoding], [allow_none])</insert><dialog title="Insert dumps">dumps(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

26432

26433

26434

<description>Convert an XML-RPC request or response into Python objects, a

26435

(params, methodname). params is a tuple of argument; methodname

26436

is a string, or None if no method name is present in the packet.

26437

If the XML-RPC packet represents a fault condition, this

26438

function will raise a Fault exception.</description>

26439

<param name="datadata" optional="0">datadata</param>

26440

<insert>loads(datadata)</insert><dialog title="Insert loads">loads(%0)</dialog><info title="Info window"></info></function>

26441

26442

</group>

26443

26444

</group>

26445

</group>

26446

26447

<description>Basic XML-RPC server implementation.

26448

The SimpleXMLRPCServer module provides a basic server

26449

framework for XML-RPC servers written in Python. Servers can either

26450

be free standing, using SimpleXMLRPCServer, or embedded in a

26451

CGI environment, using CGIXMLRPCRequestHandler.

26452

</description>

26453

26454

<description>Create a new server instance. The requestHandler parameter

26455

should be a factory for request handler instances; it defaults to

26456

SimpleXMLRPCRequestHandler. The addr and

26457

requestHandler parameters are passed to the

26458

SocketServer.TCPServer constructor. If

26459

logRequests is true (the default), requests will be logged;

26460

setting this parameter to false will turn off logging. This class

26461

provides methods for registration of functions that can be called by

26462

the XML-RPC protocol.</description>

26463

<param name="addr" optional="0">addr</param><param name="requestHandler" optional="1">requestHandler</param><param name="logRequests" optional="1">logRequests</param>

26464

<insert>SimpleXMLRPCServer(addr, [requestHandler], [logRequests])</insert><dialog title="Insert SimpleXMLRPCServer">SimpleXMLRPCServer(%0, %1, %2)</dialog><info title="Info window"></info></function>

26465

26466

26467

<description>Create a new instance to handle XML-RPC requests in a CGI

26468

environment. New in version 2.3</description>

26469

26470

<insert>CGIXMLRPCRequestHandler()</insert><dialog title="Insert CGIXMLRPCRequestHandler">CGIXMLRPCRequestHandler()</dialog><info title="Info window"></info></function>

26471

26472

26473

<description>Create a new request handler instance. This request handler

26474

supports POST requests and modifies logging so that the

26475

logRequests parameter to the SimpleXMLRPCServer

26476

constructor parameter is honored.</description>

26477

26478

<insert>SimpleXMLRPCRequestHandler()</insert><dialog title="Insert SimpleXMLRPCRequestHandler">SimpleXMLRPCRequestHandler()</dialog><info title="Info window"></info></function>

26479

26480

26481

<description>The SimpleXMLRPCServer class is based on

26482

SocketServer.TCPServer and provides a means of creating

26483

simple, stand alone XML-RPC servers.

26484

</description>

26485

26486

<description>Register a function that can respond to XML-RPC requests. If

26487

name is given, it will be the method name associated with

26488

function, otherwise function.__name__ will be

26489

used. name can be either a normal or Unicode string, and may

26490

contain characters not legal in Python identifiers, including the

26491

period character.</description>

26492

<param name="function" optional="0">function</param><param name="name" optional="1">name</param>

26493

<insert>register_function(function, [name])</insert><dialog title="Insert register_function">register_function(%0, %1)</dialog><info title="Info window"></info></function>

26494

26495

26496

<description>Register an object which is used to expose method names which have

26497

not been registered using register_function(). If

26498

instance contains a _dispatch() method, it is called

26499

with the requested method name and the parameters from the request;

26500

the return value is returned to the client as the result. If

26501

instance does not have a _dispatch() method, it is

26502

searched for an attribute matching the name of the requested method;

26503

if the requested method name contains periods, each component of the

26504

method name is searched for individually, with the effect that a

26505

simple hierarchical search is performed. The value found from this

26506

search is then called with the parameters from the request, and the

26507

return value is passed back to the client.</description>

26508

<param name="instanceinstance" optional="0">instanceinstance</param>

26509

<insert>register_instance(instanceinstance)</insert><dialog title="Insert register_instance">register_instance(%0)</dialog><info title="Info window"></info></function>

26510

26511

26512

<description>Registers the XML-RPC introspection functions system.listMethods,

26513

system.methodHelp and system.methodSignature. New in version 2.3</description>

26514

26515

<insert>register_introspection_functions()</insert><dialog title="Insert register_introspection_functions">register_introspection_functions()</dialog><info title="Info window"></info></function>

26516

26517

26518

<description>Registers the XML-RPC multicall function system.multicall.</description>

26519

26520

<insert>register_multicall_functions()</insert><dialog title="Insert register_multicall_functions">register_multicall_functions()</dialog><info title="Info window"></info></function>

26521

26522

</group>

26523

26524

<description>The CGIXMLRPCRequestHandler class can be used to handle XML-RPC requests sent to Python CGI scripts.

26525

</description>

26526

26527

<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

26528

can be either a normal or Unicode string, and may contain characters not legal in Python identifiers, including the period

26529

character.</description>

26530

<param name="function" optional="0">function</param><param name="name" optional="1">name</param>

26531

<insert>register_function(function, [name])</insert><dialog title="Insert register_function">register_function(%0, %1)</dialog><info title="Info window"></info></function>

26532

26533

26534

<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.

26535

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>

26536

<param name="instanceinstance" optional="0">instanceinstance</param>

26537

<insert>register_instance(instanceinstance)</insert><dialog title="Insert register_instance">register_instance(%0)</dialog><info title="Info window"></info></function>

26538

26539

26540

<description>Register the XML-RPC introspection functions system.listMethods, system.methodHelp and system.methodSignature.</description>

26541

26542

<insert>register_introspection_functions()</insert><dialog title="Insert register_introspection_functions">register_introspection_functions()</dialog><info title="Info window"></info></function>

26543

26544

26545

<description>Register the XML-RPC multicall function system.multicall.</description>

26546

26547

<insert>register_multicall_functions()</insert><dialog title="Insert register_multicall_functions">register_multicall_functions()</dialog><info title="Info window"></info></function>

26548

26549

26550

<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>

26551

<param name="request_text" optional="0" default=" None">request_text</param>

26552

<insert>handle_request(request_text)</insert><dialog title="Insert handle_request">handle_request(%0)</dialog><info title="Info window"></info></function>

26553

26554

</group>

26555

</group>

26556

26557

<description>Self-documenting XML-RPC server implementation.

26558

New in version 2.3

26559

The DocXMLRPCServer module extends the classes found in

26560

SimpleXMLRPCServer to serve HTML documentation in response to

26561

HTTP GET requests. Servers can either be free standing, using

26562

DocXMLRPCServer, or embedded in a CGI environment, using

26563

DocCGIXMLRPCRequestHandler.

26564

</description>

26565

26566

<description>Create a new server instance. All parameters have the same meaning as

26567

for SimpleXMLRPCServer.SimpleXMLRPCServer;

26568

requestHandler defaults to DocXMLRPCRequestHandler.</description>

26569

<param name="addr" optional="0">addr</param><param name="requestHandler" optional="1">requestHandler</param><param name="logRequests" optional="1">logRequests</param>

26570

<insert>DocXMLRPCServer(addr, [requestHandler], [logRequests])</insert><dialog title="Insert DocXMLRPCServer">DocXMLRPCServer(%0, %1, %2)</dialog><info title="Info window"></info></function>

26571

26572

26573

<description>Create a new instance to handle XML-RPC requests in a CGI environment.</description>

26574

26575

<insert>DocCGIXMLRPCRequestHandler()</insert><dialog title="Insert DocCGIXMLRPCRequestHandler">DocCGIXMLRPCRequestHandler()</dialog><info title="Info window"></info></function>

26576

26577

26578

<description>Create a new request handler instance. This request handler supports

26579

XML-RPC POST requests, documentation GET requests, and modifies

26580

logging so that the logRequests parameter to the

26581

DocXMLRPCServer constructor parameter is honored.</description>

26582

26583

<insert>DocXMLRPCRequestHandler()</insert><dialog title="Insert DocXMLRPCRequestHandler">DocXMLRPCRequestHandler()</dialog><info title="Info window"></info></function>

26584

26585

26586

<description>The DocXMLRPCServer class is derived from

26587

SimpleXMLRPCServer.SimpleXMLRPCServer and provides a means of

26588

creating self-documenting, stand alone XML-RPC servers. HTTP POST

26589

requests are handled as XML-RPC method calls. HTTP GET requests are

26590

handled by generating pydoc-style HTML documentation. This allows a

26591

server to provide its own web-based documentation.

26592

</description>

26593

26594

<description>Set the title used in the generated HTML documentation. This title

26595

will be used inside the HTML "title" element.</description>

26596

<param name="server_titleserver_title" optional="0">server_titleserver_title</param>

26597

<insert>set_server_title(server_titleserver_title)</insert><dialog title="Insert set_server_title">set_server_title(%0)</dialog><info title="Info window"></info></function>

26598

26599

26600

<description>Set the name used in the generated HTML documentation. This name will

26601

appear at the top of the generated documentation inside a "h1"

26602

element.</description>

26603

<param name="server_nameserver_name" optional="0">server_nameserver_name</param>

26604

<insert>set_server_name(server_nameserver_name)</insert><dialog title="Insert set_server_name">set_server_name(%0)</dialog><info title="Info window"></info></function>

26605

26606

26607

<description>Set the description used in the generated HTML documentation. This

26608

description will appear as a paragraph, below the server name, in the

26609

documentation.</description>

26610

<param name="server_documentationserver_documentation" optional="0">server_documentationserver_documentation</param>

26611

<insert>set_server_documentation(server_documentationserver_documentation)</insert><dialog title="Insert set_server_documentation">set_server_documentation(%0)</dialog><info title="Info window"></info></function>

26612

26613

</group>

26614

26615

<description>The DocCGIXMLRPCRequestHandler class is derived from

26616

SimpleXMLRPCServer.CGIXMLRPCRequestHandler and provides a means

26617

of creating self-documenting, XML-RPC CGI scripts. HTTP POST requests

26618

are handled as XML-RPC method calls. HTTP GET requests are handled by

26619

generating pydoc-style HTML documentation. This allows a server to

26620

provide its own web-based documentation.

26621

</description>

26622

26623

<description>Set the title used in the generated HTML documentation. This title

26624

will be used inside the HTML "title" element.</description>

26625

<param name="server_titleserver_title" optional="0">server_titleserver_title</param>

26626

<insert>set_server_title(server_titleserver_title)</insert><dialog title="Insert set_server_title">set_server_title(%0)</dialog><info title="Info window"></info></function>

26627

26628

26629

<description>Set the name used in the generated HTML documentation. This name will

26630

appear at the top of the generated documentation inside a "h1"

26631

element.</description>

26632

<param name="server_nameserver_name" optional="0">server_nameserver_name</param>

26633

<insert>set_server_name(server_nameserver_name)</insert><dialog title="Insert set_server_name">set_server_name(%0)</dialog><info title="Info window"></info></function>

26634

26635

26636

<description>Set the description used in the generated HTML documentation. This

26637

description will appear as a paragraph, below the server name, in the

26638

documentation.</description>

26639

<param name="server_documentationserver_documentation" optional="0">server_documentationserver_documentation</param>

26640

<insert>set_server_documentation(server_documentationserver_documentation)</insert><dialog title="Insert set_server_documentation">set_server_documentation(%0)</dialog><info title="Info window"></info></function>

26641

26642

</group>

26643

</group>

26644

26645

<description>A base class for developing asynchronous socket handling services.

26646

% Heavily adapted from original documentation by Sam Rushing.

26647

This module provides the basic infrastructure for writing asynchronous socket service clients and servers.

26648

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.

26649

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

26650

and protocols the companion asynchat module is invaluable.

26651

The basic idea behind both modules is to create one or more network

26652

channels, instances of class asyncore.dispatcher and

26653

asynchat.async_chat. Creating the channels adds them to a global

26654

map, used by the loop() function if you do not provide it

26655

with your own map.

26656

Once the initial channel(s) is(are) created, calling the loop()

26657

function activates channel service, which continues until the last

26658

channel (including any that have been added to the map during asynchronous

26659

service) is closed.

26660

</description>

26661

26662

<description>Enter a polling loop that only terminates after all open channels

26663

have been closed. All arguments are optional. The timeout

26664

argument sets the timeout parameter for the appropriate

26665

select() or poll() call, measured in seconds;

26666

the default is 30 seconds. The use_poll parameter, if true,

26667

indicates that poll() should be used in preference to

26668

select() (the default is False). The map parameter

26669

is a dictionary whose items are the channels to watch. As channels

26670

are closed they are deleted from their map. If map is

26671

omitted, a global map is used (this map is updated by the default

26672

class __init__()

26673

-- make sure you extend, rather than override, __init__()

26674

if you want to retain this behavior).

26675

Channels (instances of asyncore.dispatcher, asynchat.async_chat

26676

and subclasses thereof) can freely be mixed in the map.</description>

26677

<param name="timeout" optional="0">timeout</param><param name="use_poll" optional="1">use_poll</param><param name="map" optional="1">map</param>

26678

<insert>loop(timeout, [use_poll], [map])</insert><dialog title="Insert loop">loop(%0, %1, %2)</dialog><info title="Info window"></info></function>

26679

26680

26681

<description>The dispatcher class is a thin wrapper around a low-level socket object.

26682

To make it more useful, it has a few methods for event-handling which are called

26683

from the asynchronous loop. Otherwise, it can be treated as a normal non-blocking socket object.

26684

Two class attributes can be modified, to improve performance,

26685

or possibly even to conserve memory.

26686

{ac_in_buffer_size}

26687

The asynchronous input buffer size (default 4096).

26688

{ac_out_buffer_size}

26689

The asynchronous output buffer size (default 4096).

26690

The firing of low-level events at certain times or in certain connection

26691

states tells the asynchronous loop that certain higher-level events have

26692

taken place. For example, if we have asked for a socket to connect to

26693

another host, we know that the connection has been made when the socket

26694

becomes writable for the first time (at this point you know that you may

26695

write to it with the expectation of success). The implied higher-level

26696

events are:

26697

{l|l}{code}{Event}{Description}

26698

handle_connect(){Implied by the first write event}

26699

handle_close(){Implied by a read event with no data available}

26700

handle_accept(){Implied by a read event on a listening socket}

26701

During asynchronous processing, each mapped channel's readable()

26702

and writable() methods are used to determine whether the channel's

26703

socket should be added to the list of channels select()ed or

26704

poll()ed for read and write events.</description>

26705

26706

<insert>dispatcher()</insert><dialog title="Insert dispatcher">dispatcher()</dialog><info title="Info window"></info></function>

26707

26708

26709

<description>Called when the asynchronous loop detects that a read()

26710

call on the channel's socket will succeed.</description>

26711

26712

<insert>handle_read()</insert><dialog title="Insert handle_read">handle_read()</dialog><info title="Info window"></info></function>

26713

26714

26715

<description>Called when the asynchronous loop detects that a writable socket

26716

can be written. Often this method will implement the necessary buffering for performance. For example:

26717

def handle_write(self):

26718

sent = self.send(self.buffer)

26719

self.buffer = self.buffer[sent:]

26720

</description>

26721

26722

<insert>handle_write()</insert><dialog title="Insert handle_write">handle_write()</dialog><info title="Info window"></info></function>

26723

26724

26725

<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>

26726

26727

<insert>handle_expt()</insert><dialog title="Insert handle_expt">handle_expt()</dialog><info title="Info window"></info></function>

26728

26729

26730

<description>Called when the active opener's socket actually makes a connection.

26731

Might send a ``welcome'' banner, or initiate a protocol

26732

negotiation with the remote endpoint, for example.</description>

26733

26734

<insert>handle_connect()</insert><dialog title="Insert handle_connect">handle_connect()</dialog><info title="Info window"></info></function>

26735

26736

26737

<description>Called when the socket is closed.</description>

26738

26739

<insert>handle_close()</insert><dialog title="Insert handle_close">handle_close()</dialog><info title="Info window"></info></function>

26740

26741

26742

<description>Called when an exception is raised and not otherwise handled. The default

26743

version prints a condensed traceback.</description>

26744

26745

<insert>handle_error()</insert><dialog title="Insert handle_error">handle_error()</dialog><info title="Info window"></info></function>

26746

26747

26748

<description>Called on listening channels (passive openers) when a connection can be established with a new remote endpoint that

26749

has issued a connect() call for the local endpoint.</description>

26750

26751

<insert>handle_accept()</insert><dialog title="Insert handle_accept">handle_accept()</dialog><info title="Info window"></info></function>

26752

26753

26754

<description>Called each time around the asynchronous loop to determine whether a

26755

channel's socket should be added to the list on which read events can

26756

occur. The default method simply returns True, indicating that by default, all channels will be interested in

26757

read events.</description>

26758

26759

<insert>readable()</insert><dialog title="Insert readable">readable()</dialog><info title="Info window"></info></function>

26760

26761

26762

<description>Called each time around the asynchronous loop to determine whether a

26763

channel's socket should be added to the list on which write events can

26764

occur. The default method simply returns True, indicating that by default, all channels will be interested in

26765

write events.</description>

26766

26767

<insert>writable()</insert><dialog title="Insert writable">writable()</dialog><info title="Info window"></info></function>

26768

26769

26770

<description>This is identical to the creation of a normal socket, and will use the same options for creation. Refer to the

26771

socket documentation for information on creating

26772

sockets.</description>

26773

<param name="family" optional="0">family</param><param name="type type" optional="0">type type</param>

26774

<insert>create_socket(family, type type)</insert><dialog title="Insert create_socket">create_socket(%0, %1)</dialog><info title="Info window"></info></function>

26775

26776

26777

<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>

26778

<param name="addressaddress" optional="0">addressaddress</param>

26779

<insert>connect(addressaddress)</insert><dialog title="Insert connect">connect(%0)</dialog><info title="Info window"></info></function>

26780

26781

26782

<description>Send data to the remote end-point of the socket.</description>

26783

<param name="datadata" optional="0">datadata</param>

26784

<insert>send(datadata)</insert><dialog title="Insert send">send(%0)</dialog><info title="Info window"></info></function>

26785

26786

26787

<description>Read at most buffer_size bytes from the socket's remote end-point.

26788

An empty string implies that the channel has been closed from the other

26789

end.</description>

26790

<param name="buffer_sizebuffer_size" optional="0">buffer_sizebuffer_size</param>

26791

<insert>recv(buffer_sizebuffer_size)</insert><dialog title="Insert recv">recv(%0)</dialog><info title="Info window"></info></function>

26792

26793

26794

<description>Listen for connections made to the socket. The backlog

26795

argument specifies the maximum number of queued connections

26796

and should be at least 1; the maximum value is

26797

system-dependent (usually 5).</description>

26798

<param name="backlogbacklog" optional="0">backlogbacklog</param>

26799

<insert>listen(backlogbacklog)</insert><dialog title="Insert listen">listen(%0)</dialog><info title="Info window"></info></function>

26800

26801

26802

<description>Bind the socket to address. The socket must not already

26803

be bound. (The format of address depends on the address

26804

family --- see above.)</description>

26805

<param name="addressaddress" optional="0">addressaddress</param>

26806

<insert>bind(addressaddress)</insert><dialog title="Insert bind">bind(%0)</dialog><info title="Info window"></info></function>

26807

26808

26809

<description>Accept a connection. The socket must be bound to an address

26810

and listening for connections. The return value is a pair

26811

(conn, address) where conn is a

26812

new socket object usable to send and receive data on

26813

the connection, and address is the address bound to the

26814

socket on the other end of the connection.</description>

26815

26816

<insert>accept()</insert><dialog title="Insert accept">accept()</dialog><info title="Info window"></info></function>

26817

26818

26819

<description>Close the socket. All future operations on the socket object

26820

will fail. The remote end-point will receive no more data (after

26821

queued data is flushed). Sockets are automatically closed

26822

when they are garbage-collected.</description>

26823

26824

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

26825

26826

26827

</group>

26828

</group>

26829

26830

<description>Support for asynchronous command/response protocols.

26831

This module builds on the asyncore infrastructure,

26832

simplifying asynchronous clients and servers and making it easier to

26833

handle protocols whose elements are terminated by arbitrary strings, or

26834

are of variable length. asynchat defines the abstract class

26835

async_chat that you subclass, providing implementations of the

26836

collect_incoming_data() and found_terminator()

26837

methods. It uses the same asynchronous loop as asyncore, and

26838

the two types of channel, asyncore.dispatcher and

26839

asynchat.async_chat, can freely be mixed in the channel map.

26840

Typically an asyncore.dispatcher server channel generates new

26841

asynchat.async_chat channel objects as it receives incoming

26842

connection requests. </description>

26843

26844

<description>This class is an abstract subclass of asyncore.dispatcher. To make

26845

practical use of the code you must subclass async_chat, providing

26846

meaningful collect_incoming_data() and found_terminator()

26847

methods. The asyncore.dispatcher methods can be

26848

used, although not all make sense in a message/response context. Like asyncore.dispatcher, async_chat defines a set of events

26849

that are generated by an analysis of socket conditions after a

26850

select() call. Once the polling loop has been started the

26851

async_chat object's methods are called by the event-processing

26852

framework with no action on the part of the programmer.

26853

Unlike asyncore.dispatcher, async_chat allows you to define

26854

a first-in-first-out queue (fifo) of producers. A producer need have

26855

only one method, more(), which should return data to be transmitted

26856

on the channel. The producer indicates exhaustion (i.e. that it contains

26857

no more data) by having its more() method return the empty string. At

26858

this point the async_chat object removes the producer from the fifo

26859

and starts using the next producer, if any. When the producer fifo is empty

26860

the handle_write() method does nothing. You use the channel object's

26861

set_terminator() method to describe how to recognize the end

26862

of, or an important breakpoint in, an incoming transmission from the

26863

remote endpoint.

26864

To build a functioning async_chat subclass your input methods collect_incoming_data() and

26865

found_terminator() must handle the data that the channel receives

26866

asynchronously. The methods are described below.</description>

26867

26868

<insert>async_chat()</insert><dialog title="Insert async_chat">async_chat()</dialog><info title="Info window"></info></function>

26869

26870

26871

<description>Pushes a None on to the producer fifo. When this producer is

26872

popped off the fifo it causes the channel to be closed.</description>

26873

26874

<insert>close_when_done()</insert><dialog title="Insert close_when_done">close_when_done()</dialog><info title="Info window"></info></function>

26875

26876

26877

<description>Called with data holding an arbitrary amount of received data.

26878

The default method, which must be overridden, raises a NotImplementedError exception.</description>

26879

<param name="datadata" optional="0">datadata</param>

26880

<insert>collect_incoming_data(datadata)</insert><dialog title="Insert collect_incoming_data">collect_incoming_data(%0)</dialog><info title="Info window"></info></function>

26881

26882

26883

<description>In emergencies this method will discard any data held in the input and/or

26884

output buffers and the producer fifo.</description>

26885

26886

<insert>discard_buffers()</insert><dialog title="Insert discard_buffers">discard_buffers()</dialog><info title="Info window"></info></function>

26887

26888

26889

<description>Called when the incoming data stream matches the termination condition

26890

set by set_terminator. The default method, which must be overridden,

26891

raises a NotImplementedError exception. The buffered input data should

26892

be available via an instance attribute.</description>

26893

26894

<insert>found_terminator()</insert><dialog title="Insert found_terminator">found_terminator()</dialog><info title="Info window"></info></function>

26895

26896

26897

<description>Returns the current terminator for the channel.</description>

26898

26899

<insert>get_terminator()</insert><dialog title="Insert get_terminator">get_terminator()</dialog><info title="Info window"></info></function>

26900

26901

26902

<description>Called when the channel is closed. The default method silently closes

26903

the channel's socket.</description>

26904

26905

<insert>handle_close()</insert><dialog title="Insert handle_close">handle_close()</dialog><info title="Info window"></info></function>

26906

26907

26908

<description>Called when a read event fires on the channel's socket in the

26909

asynchronous loop. The default method checks for the termination

26910

condition established by set_terminator(), which can be either

26911

the appearance of a particular string in the input stream or the receipt

26912

of a particular number of characters. When the terminator is found,

26913

handle_read calls the found_terminator() method after

26914

calling collect_incoming_data() with any data preceding the

26915

terminating condition.</description>

26916

26917

<insert>handle_read()</insert><dialog title="Insert handle_read">handle_read()</dialog><info title="Info window"></info></function>

26918

26919

26920

<description>Called when the application may write data to the channel. The default method calls the initiate_send() method, which in turn

26921

will call refill_buffer() to collect data from the producer

26922

fifo associated with the channel.</description>

26923

26924

<insert>handle_write()</insert><dialog title="Insert handle_write">handle_write()</dialog><info title="Info window"></info></function>

26925

26926

26927

<description>Creates a simple_producer object (see below) containing the data and

26928

pushes it on to the channel's producer_fifo to ensure its

26929

transmission. This is all you need to do to have the channel write

26930

the data out to the network, although it is possible to use your

26931

own producers in more complex schemes to implement encryption and

26932

chunking, for example.</description>

26933

<param name="datadata" optional="0">datadata</param>

26934

<insert>push(datadata)</insert><dialog title="Insert push">push(%0)</dialog><info title="Info window"></info></function>

26935

26936

26937

<description>Takes a producer object and adds it to the producer fifo associated with

26938

the channel. When all currently-pushed producers have been exhausted

26939

the channel will consume this producer's data by calling its

26940

more() method and send the data to the remote endpoint.</description>

26941

<param name="producerproducer" optional="0">producerproducer</param>

26942

<insert>push_with_producer(producerproducer)</insert><dialog title="Insert push_with_producer">push_with_producer(%0)</dialog><info title="Info window"></info></function>

26943

26944

26945

<description>Should return True for the channel to be included in the set of

26946

channels tested by the select() loop for readability.</description>

26947

26948

<insert>readable()</insert><dialog title="Insert readable">readable()</dialog><info title="Info window"></info></function>

26949

26950

26951

<description>Refills the output buffer by calling the more() method of the

26952

producer at the head of the fifo. If it is exhausted then the

26953

producer is popped off the fifo and the next producer is activated.

26954

If the current producer is, or becomes, None then the channel

26955

is closed.</description>

26956

26957

<insert>refill_buffer()</insert><dialog title="Insert refill_buffer">refill_buffer()</dialog><info title="Info window"></info></function>

26958

26959

26960

<description>Sets the terminating condition to be recognised on the channel. term

26961

may be any of three types of value, corresponding to three different ways

26962

to handle incoming protocol data.

26963

{l|l}{}{term}{Description}

26964

string{Will call found_terminator() when the

26965

string is found in the input stream}

26966

integer{Will call found_terminator() when the

26967

indicated number of characters have been received}

26968

None{The channel continues to collect data forever}

26969

Note that any data following the terminator will be available for reading by

26970

the channel after found_terminator() is called.</description>

26971

<param name="termterm" optional="0">termterm</param>

26972

<insert>set_terminator(termterm)</insert><dialog title="Insert set_terminator">set_terminator(%0)</dialog><info title="Info window"></info></function>

26973

26974

26975

<description>Should return True as long as items remain on the producer fifo,

26976

or the channel is connected and the channel's output buffer is non-empty.</description>

26977

26978

<insert>writable()</insert><dialog title="Insert writable">writable()</dialog><info title="Info window"></info></function>

26979

26980

26981

26982

<description>A simple_producer takes a chunk of data and an optional buffer size.

26983

Repeated calls to its more() method yield successive chunks of the

26984

data no larger than buffer_size.</description>

26985

<param name="data" optional="0">data</param><param name="buffer_size" optional="1" default="512">buffer_size</param>

26986

<insert>simple_producer(data, [buffer_size=512])</insert><dialog title="Insert simple_producer">simple_producer(%0, %1)</dialog><info title="Info window"></info></function>

26987

26988

26989

<description>Produces the next chunk of information from the producer, or returns the empty string.</description>

26990

26991

26992

26993

26994

<description>Each channel maintains a fifo holding data which has been pushed by the

26995

application but not yet popped for writing to the channel.

26996

A fifo is a list used to hold data and/or producers until they are required.

26997

If the list argument is provided then it should contain producers or

26998

data items to be written to the channel.</description>

26999

27000

27001

27002

27003

<description>Returns True iff the fifo is empty.</description>

27004

27005

<insert>is_empty()</insert><dialog title="Insert is_empty">is_empty()</dialog><info title="Info window"></info></function>

27006

27007

27008

<description>Returns the least-recently push()ed item from the fifo.</description>

27009

27010

<insert>first()</insert><dialog title="Insert first">first()</dialog><info title="Info window"></info></function>

27011

27012

27013

<description>Adds the given data (which may be a string or a producer object) to the

27014

producer fifo.</description>

27015

<param name="datadata" optional="0">datadata</param>

27016

<insert>push(datadata)</insert><dialog title="Insert push">push(%0)</dialog><info title="Info window"></info></function>

27017

27018

27019

<description>If the fifo is not empty, returns True, first(), deleting the popped

27020

item. Returns False, None for an empty fifo.</description>

27021

27022

27023

27024

27025

<description>Returns True if string haystack ends with any non-empty

27026

prefix of string needle.</description>

27027

<param name="haystack" optional="0">haystack</param><param name="needle needle" optional="0">needle needle</param>

27028

<insert>find_prefix_at_end(haystack, needle needle)</insert><dialog title="Insert find_prefix_at_end">find_prefix_at_end(%0, %1)</dialog><info title="Info window"></info></function>

27029

27030

</group>

27031

27032

</group>

27033

</group>

27034

</group>

27035

27036

27037

<description>Generic output formatter and device interface.

27038

This module supports two interface definitions, each with multiple

27039

implementations. The formatter interface is used by the

27040

HTMLParser class of the htmllib module, and the

27041

writer interface is required by the formatter interface.

27042

(class in htmllib){HTMLParser}

27043

Formatter objects transform an abstract flow of formatting events into

27044

specific output events on writer objects. Formatters manage several

27045

stack structures to allow various properties of a writer object to be

27046

changed and restored; writers need not be able to handle relative

27047

changes nor any sort of ``change back'' operation. Specific writer

27048

properties which may be controlled via formatter objects are

27049

horizontal alignment, font, and left margin indentations. A mechanism

27050

is provided which supports providing arbitrary, non-exclusive style

27051

settings to a writer as well. Additional interfaces facilitate

27052

formatting events which are not reversible, such as paragraph

27053

separation.

27054

Writer objects encapsulate device interfaces. Abstract devices, such

27055

as file formats, are supported as well as physical devices. The

27056

provided implementations all work with abstract devices. The

27057

interface makes available mechanisms for setting the properties which

27058

formatter objects manage and inserting data into the output.

27059

</description>

27060

27061

<description>Interfaces to create formatters are dependent on the specific

27062

formatter class being instantiated. The interfaces described below

27063

are the required interfaces which all formatters must support once

27064

initialized.

27065

One data element is defined at the module level:

27066

{AS_IS}

27067

Value which can be used in the font specification passed to the

27068

push_font() method described below, or as the new value to any

27069

other push_property() method. Pushing the AS_IS

27070

value allows the corresponding pop_property() method to

27071

be called without having to track whether the property was changed.

27072

The following attributes are defined for formatter instance objects:

27073

[formatter]{writer}

27074

The writer instance with which the formatter interacts.

27075

</description>

27076

27077

<description>Close any open paragraphs and insert at least blanklines

27078

before the next paragraph.</description>

27079

<param name="blanklinesblanklines" optional="0">blanklinesblanklines</param>

27080

<insert>end_paragraph(blanklinesblanklines)</insert><dialog title="Insert end_paragraph">end_paragraph(%0)</dialog><info title="Info window"></info></function>

27081

27082

27083

<description>Add a hard line break if one does not already exist. This does not

27084

break the logical paragraph.</description>

27085

27086

<insert>add_line_break()</insert><dialog title="Insert add_line_break">add_line_break()</dialog><info title="Info window"></info></function>

27087

27088

27089

<description>Insert a horizontal rule in the output. A hard break is inserted if

27090

there is data in the current paragraph, but the logical paragraph is

27091

not broken. The arguments and keywords are passed on to the writer's

27092

send_line_break() method.</description>

27093

27094

27095

27096

27097

<description>Provide data which should be formatted with collapsed whitespace.

27098

Whitespace from preceding and successive calls to

27099

add_flowing_data() is considered as well when the whitespace

27100

collapse is performed. The data which is passed to this method is

27101

expected to be word-wrapped by the output device. Note that any

27102

word-wrapping still must be performed by the writer object due to the

27103

need to rely on device and font information.</description>

27104

<param name="datadata" optional="0">datadata</param>

27105

<insert>add_flowing_data(datadata)</insert><dialog title="Insert add_flowing_data">add_flowing_data(%0)</dialog><info title="Info window"></info></function>

27106

27107

27108

<description>Provide data which should be passed to the writer unchanged.

27109

Whitespace, including newline and tab characters, are considered legal

27110

in the value of data.</description>

27111

<param name="datadata" optional="0">datadata</param>

27112

<insert>add_literal_data(datadata)</insert><dialog title="Insert add_literal_data">add_literal_data(%0)</dialog><info title="Info window"></info></function>

27113

27114

27115

<description>Insert a label which should be placed to the left of the current left

27116

margin. This should be used for constructing bulleted or numbered

27117

lists. If the format value is a string, it is interpreted as a

27118

format specification for counter, which should be an integer.

27119

The result of this formatting becomes the value of the label; if

27120

format is not a string it is used as the label value directly.

27121

The label value is passed as the only argument to the writer's

27122

send_label_data() method. Interpretation of non-string label

27123

values is dependent on the associated writer.

27124

Format specifications are strings which, in combination with a counter

27125

value, are used to compute label values. Each character in the format

27126

string is copied to the label value, with some characters recognized

27127

to indicate a transform on the counter value. Specifically, the

27128

character 1 represents the counter value formatter as an

27129

Arabic number, the characters A and a

27130

represent alphabetic representations of the counter value in upper and

27131

lower case, respectively, and I and i

27132

represent the counter value in Roman numerals, in upper and lower

27133

case. Note that the alphabetic and roman transforms require that the

27134

counter value be greater than zero.</description>

27135

<param name="format" optional="0">format</param><param name="counter counter" optional="0">counter counter</param>

27136

<insert>add_label_data(format, counter counter)</insert><dialog title="Insert add_label_data">add_label_data(%0, %1)</dialog><info title="Info window"></info></function>

27137

27138

27139

<description>Send any pending whitespace buffered from a previous call to

27140

add_flowing_data() to the associated writer object. This

27141

should be called before any direct manipulation of the writer object.</description>

27142

27143

<insert>flush_softspace()</insert><dialog title="Insert flush_softspace">flush_softspace()</dialog><info title="Info window"></info></function>

27144

27145

27146

<description>Push a new alignment setting onto the alignment stack. This may be

27147

AS_IS if no change is desired. If the alignment value is

27148

changed from the previous setting, the writer's new_alignment()

27149

method is called with the align value.</description>

27150

<param name="alignalign" optional="0">alignalign</param>

27151

<insert>push_alignment(alignalign)</insert><dialog title="Insert push_alignment">push_alignment(%0)</dialog><info title="Info window"></info></function>

27152

27153

27154

<description>Restore the previous alignment.</description>

27155

27156

<insert>pop_alignment()</insert><dialog title="Insert pop_alignment">pop_alignment()</dialog><info title="Info window"></info></function>

27157

27158

27159

<description>Change some or all font properties of the writer object. Properties

27160

which are not set to AS_IS are set to the values passed in

27161

while others are maintained at their current settings. The writer's

27162

new_font() method is called with the fully resolved font

27163

specification.</description>

27164

<param name="(size" optional="0">(size</param><param name="italic" optional="0">italic</param><param name="bold" optional="0">bold</param><param name="teletype)" optional="0">teletype)</param>

27165

<insert>push_font((size, italic, bold, teletype))</insert><dialog title="Insert push_font">push_font(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

27166

27167

27168

<description>Restore the previous font.</description>

27169

27170

27171

27172

27173

<description>Increase the number of left margin indentations by one, associating

27174

the logical tag margin with the new indentation. The initial

27175

margin level is 0. Changed values of the logical tag must be

27176

true values; false values other than AS_IS are not

27177

sufficient to change the margin.</description>

27178

<param name="marginmargin" optional="0">marginmargin</param>

27179

<insert>push_margin(marginmargin)</insert><dialog title="Insert push_margin">push_margin(%0)</dialog><info title="Info window"></info></function>

27180

27181

27182

<description>Restore the previous margin.</description>

27183

27184

<insert>pop_margin()</insert><dialog title="Insert pop_margin">pop_margin()</dialog><info title="Info window"></info></function>

27185

27186

27187

<description>Push any number of arbitrary style specifications. All styles are

27188

pushed onto the styles stack in order. A tuple representing the

27189

entire stack, including AS_IS values, is passed to the

27190

writer's new_styles() method.</description>

27191

<param name="*styles*styles" optional="0">*styles*styles</param>

27192

<insert>push_style(*styles*styles)</insert><dialog title="Insert push_style">push_style(%0)</dialog><info title="Info window"></info></function>

27193

27194

27195

<description>Pop the last n style specifications passed to

27196

push_style(). A tuple representing the revised stack,

27197

including AS_IS values, is passed to the writer's

27198

new_styles() method.</description>

27199

27200

<insert>pop_style(n)</insert><dialog title="Insert pop_style">pop_style(%0)</dialog><info title="Info window"></info></function>

27201

27202

27203

<description>Set the spacing style for the writer.</description>

27204

<param name="spacingspacing" optional="0">spacingspacing</param>

27205

<insert>set_spacing(spacingspacing)</insert><dialog title="Insert set_spacing">set_spacing(%0)</dialog><info title="Info window"></info></function>

27206

27207

27208

<description>Inform the formatter that data has been added to the current paragraph

27209

out-of-band. This should be used when the writer has been manipulated

27210

directly. The optional flag argument can be set to false if

27211

the writer manipulations produced a hard line break at the end of the

27212

output.</description>

27213

27214

<insert>assert_line_data(flag)</insert><dialog title="Insert assert_line_data">assert_line_data(%0)</dialog><info title="Info window"></info></function>

27215

27216

</group>

27217

27218

<description>Two implementations of formatter objects are provided by this module.

27219

Most applications may use one of these classes without modification or

27220

subclassing.

27221

</description>

27222

27223

<description>A formatter which does nothing. If writer is omitted, a

27224

NullWriter instance is created. No methods of the writer are

27225

called by NullFormatter instances. Implementations should

27226

inherit from this class if implementing a writer interface but don't

27227

need to inherit any implementation.</description>

27228

<param name="writer" optional="0">writer</param>

27229

<insert>NullFormatter(writer)</insert><dialog title="Insert NullFormatter">NullFormatter(%0)</dialog><info title="Info window"></info></function>

27230

27231

27232

<description>The standard formatter. This implementation has demonstrated wide

27233

applicability to many writers, and may be used directly in most

27234

circumstances. It has been used to implement a full-featured

27235

World Wide Web browser.</description>

27236

<param name="writerwriter" optional="0">writerwriter</param>

27237

<insert>AbstractFormatter(writerwriter)</insert><dialog title="Insert AbstractFormatter">AbstractFormatter(%0)</dialog><info title="Info window"></info></function>

27238

27239

</group>

27240

27241

<description>Interfaces to create writers are dependent on the specific writer

27242

class being instantiated. The interfaces described below are the

27243

required interfaces which all writers must support once initialized.

27244

Note that while most applications can use the

27245

AbstractFormatter class as a formatter, the writer must

27246

typically be provided by the application.

27247

</description>

27248

27249

<description>Flush any buffered output or device control events.</description>

27250

27251

<insert>flush()</insert><dialog title="Insert flush">flush()</dialog><info title="Info window"></info></function>

27252

27253

27254

<description>Set the alignment style. The align value can be any object,

27255

but by convention is a string or None, where None

27256

indicates that the writer's ``preferred'' alignment should be used.

27257

Conventional align values are 'left', 'center',

27258

'right', and 'justify'.</description>

27259

<param name="alignalign" optional="0">alignalign</param>

27260

<insert>new_alignment(alignalign)</insert><dialog title="Insert new_alignment">new_alignment(%0)</dialog><info title="Info window"></info></function>

27261

27262

27263

<description>Set the font style. The value of font will be None,

27264

indicating that the device's default font should be used, or a tuple

27265

of the form (size, italic, bold,

27266

teletype). Size will be a string indicating the size of

27267

font that should be used; specific strings and their interpretation

27268

must be defined by the application. The italic, bold, and

27269

teletype values are Boolean values specifying which of those

27270

font attributes should be used.</description>

27271

<param name="fontfont" optional="0">fontfont</param>

27272

<insert>new_font(fontfont)</insert><dialog title="Insert new_font">new_font(%0)</dialog><info title="Info window"></info></function>

27273

27274

27275

<description>Set the margin level to the integer level and the logical tag

27276

to margin. Interpretation of the logical tag is at the

27277

writer's discretion; the only restriction on the value of the logical

27278

tag is that it not be a false value for non-zero values of

27279

level.</description>

27280

<param name="margin" optional="0">margin</param><param name="level level" optional="0">level level</param>

27281

<insert>new_margin(margin, level level)</insert><dialog title="Insert new_margin">new_margin(%0, %1)</dialog><info title="Info window"></info></function>

27282

27283

27284

<description>Set the spacing style to spacing.</description>

27285

<param name="spacingspacing" optional="0">spacingspacing</param>

27286

<insert>new_spacing(spacingspacing)</insert><dialog title="Insert new_spacing">new_spacing(%0)</dialog><info title="Info window"></info></function>

27287

27288

27289

<description>Set additional styles. The styles value is a tuple of

27290

arbitrary values; the value AS_IS should be ignored. The

27291

styles tuple may be interpreted either as a set or as a stack

27292

depending on the requirements of the application and writer

27293

implementation.</description>

27294

<param name="stylesstyles" optional="0">stylesstyles</param>

27295

<insert>new_styles(stylesstyles)</insert><dialog title="Insert new_styles">new_styles(%0)</dialog><info title="Info window"></info></function>

27296

27297

27298

<description>Break the current line.</description>

27299

27300

<insert>send_line_break()</insert><dialog title="Insert send_line_break">send_line_break()</dialog><info title="Info window"></info></function>

27301

27302

27303

<description>Produce a paragraph separation of at least blankline blank

27304

lines, or the equivalent. The blankline value will be an

27305

integer. Note that the implementation will receive a call to

27306

send_line_break() before this call if a line break is needed; this method should not include ending the last line of the paragraph.

27307

It is only responsible for vertical spacing between paragraphs.</description>

27308

<param name="blanklineblankline" optional="0">blanklineblankline</param>

27309

<insert>send_paragraph(blanklineblankline)</insert><dialog title="Insert send_paragraph">send_paragraph(%0)</dialog><info title="Info window"></info></function>

27310

27311

27312

<description>Display a horizontal rule on the output device. The arguments to this

27313

method are entirely application- and writer-specific, and should be

27314

interpreted with care. The method implementation may assume that a

27315

line break has already been issued via send_line_break().</description>

27316

27317

27318

27319

27320

<description>Output character data which may be word-wrapped and re-flowed as

27321

needed. Within any sequence of calls to this method, the writer may

27322

assume that spans of multiple whitespace characters have been

27323

collapsed to single space characters.</description>

27324

<param name="datadata" optional="0">datadata</param>

27325

<insert>send_flowing_data(datadata)</insert><dialog title="Insert send_flowing_data">send_flowing_data(%0)</dialog><info title="Info window"></info></function>

27326

27327

27328

<description>Output character data which has already been formatted

27329

for display. Generally, this should be interpreted to mean that line

27330

breaks indicated by newline characters should be preserved and no new

27331

line breaks should be introduced. The data may contain embedded

27332

newline and tab characters, unlike data provided to the

27333

send_formatted_data() interface.</description>

27334

<param name="datadata" optional="0">datadata</param>

27335

<insert>send_literal_data(datadata)</insert><dialog title="Insert send_literal_data">send_literal_data(%0)</dialog><info title="Info window"></info></function>

27336

27337

27338

<description>Set data to the left of the current left margin, if possible.

27339

The value of data is not restricted; treatment of non-string

27340

values is entirely application- and writer-dependent. This method

27341

will only be called at the beginning of a line.</description>

27342

<param name="datadata" optional="0">datadata</param>

27343

<insert>send_label_data(datadata)</insert><dialog title="Insert send_label_data">send_label_data(%0)</dialog><info title="Info window"></info></function>

27344

27345

</group>

27346

27347

<description>Three implementations of the writer object interface are provided as

27348

examples by this module. Most applications will need to derive new

27349

writer classes from the NullWriter class.

27350

</description>

27351

27352

<description>A writer which only provides the interface definition; no actions are

27353

taken on any methods. This should be the base class for all writers

27354

which do not need to inherit any implementation methods.</description>

27355

27356

<insert>NullWriter()</insert><dialog title="Insert NullWriter">NullWriter()</dialog><info title="Info window"></info></function>

27357

27358

27359

<description>A writer which can be used in debugging formatters, but not much

27360

else. Each method simply announces itself by printing its name and

27361

arguments on standard output.</description>

27362

27363

<insert>AbstractWriter()</insert><dialog title="Insert AbstractWriter">AbstractWriter()</dialog><info title="Info window"></info></function>

27364

27365

27366

<description>Simple writer class which writes output on the file object passed in

27367

as file or, if file is omitted, on standard output. The

27368

output is simply word-wrapped to the number of columns specified by

27369

maxcol. This class is suitable for reflowing a sequence of

27370

paragraphs.</description>

27371

<param name="file" optional="0">file</param><param name="maxcol" optional="1" default=" 72">maxcol</param>

27372

<insert>DumbWriter(file, [maxcol= 72])</insert><dialog title="Insert DumbWriter">DumbWriter(%0, %1)</dialog><info title="Info window"></info></function>

27373

27374

</group>

27375

</group>

27376

27377

<description>Package supporting the parsing, manipulating, and

27378

generating email messages, including MIME documents.

27379

New in version 2.2

27380

The email package is a library for managing email messages,

27381

including MIME and other 2822-based message documents. It

27382

subsumes most of the functionality in several older standard modules

27383

such as rfc822, mimetools,

27384

multifile, and other non-standard packages such as

27385

mimecntl. It is specifically not designed to do any

27386

sending of email messages to SMTP (2821) servers; that is the

27387

function of the smtplib module. The email

27388

package attempts to be as RFC-compliant as possible, supporting in

27389

addition to 2822, such MIME-related RFCs as

27390

2045-2047, and 2231.

27391

The primary distinguishing feature of the email package is

27392

that it splits the parsing and generating of email messages from the

27393

internal object model representation of email. Applications

27394

using the email package deal primarily with objects; you can

27395

add sub-objects to messages, remove sub-objects from messages,

27396

completely re-arrange the contents, etc. There is a separate parser

27397

and a separate generator which handles the transformation from flat

27398

text to the object model, and then back to flat text again. There

27399

are also handy subclasses for some common MIME object types, and a few

27400

miscellaneous utilities that help with such common tasks as extracting

27401

and parsing message field values, creating RFC-compliant dates, etc.

27402

The following sections describe the functionality of the

27403

email package. The ordering follows a progression that

27404

should be common in applications: an email message is read as flat

27405

text from a file or other source, the text is parsed to produce the

27406

object structure of the email message, this structure is manipulated,

27407

and finally rendered back into flat text.

27408

It is perfectly feasible to create the object structure out of whole

27409

cloth --- i.e. completely from scratch. From there, a similar

27410

progression can be taken as above.

27411

Also included are detailed specifications of all the classes and

27412

modules that the email package provides, the exception

27413

classes you might encounter while using the email package,

27414

some auxiliary utilities, and a few examples. For users of the older

27415

mimelib package, or previous versions of the email

27416

package, a section on differences and porting is provided.

27417

smtplib{SMTP protocol client}

27418

</description>

27419

27420

<description>emailmessage

27421

</description>

27422

</group>

27423

27424

<description>emailparser

27425

</description>

27426

</group>

27427

27428

<description>emailgenerator

27429

</description>

27430

</group>

27431

27432

<description>emailmimebase

27433

</description>

27434

</group>

27435

27436

<description>emailheaders

27437

</description>

27438

</group>

27439

27440

<description>emailcharsets

27441

</description>

27442

</group>

27443

27444

<description>emailencoders

27445

</description>

27446

</group>

27447

27448

<description>emailexc

27449

</description>

27450

</group>

27451

27452

<description>emailutil

27453

</description>

27454

</group>

27455

27456

<description>emailiter

27457

</description>

27458

</group>

27459

27460

<description>Version 1 of the email package was bundled with Python

27461

releases up to Python 2.2.1. Version 2 was developed for the Python

27462

2.3 release, and backported to Python 2.2.2. It was also available as

27463

a separate distutils based package. email version 2 is

27464

almost entirely backward compatible with version 1, with the

27465

following differences:

27466

The email.Header and email.Charset modules

27467

have been added.

27468

The pickle format for Message instances has changed.

27469

Since this was never (and still isn't) formally defined, this

27470

isn't considered a backward incompatibility. However if your

27471

application pickles and unpickles Message instances, be

27472

aware that in email version 2, Message

27473

instances now have private variables _charset and

27474

_default_type.

27475

Several methods in the Message class have been

27476

deprecated, or their signatures changed. Also, many new methods

27477

have been added. See the documentation for the Message

27478

class for details. The changes should be completely backward

27479

compatible.

27480

The object structure has changed in the face of

27481

message/rfc822 content types. In email

27482

version 1, such a type would be represented by a scalar payload,

27483

i.e. the container message's is_multipart() returned

27484

false, get_payload() was not a list object, but a single

27485

Message instance.

27486

This structure was inconsistent with the rest of the package, so

27487

the object representation for message/rfc822 content

27488

types was changed. In email version 2, the container

27489

does return True from is_multipart(), and

27490

get_payload() returns a list containing a single

27491

Message item.

27492

Note that this is one place that backward compatibility could

27493

not be completely maintained. However, if you're already

27494

testing the return type of get_payload(), you should be

27495

fine. You just need to make sure your code doesn't do a

27496

set_payload() with a Message instance on a

27497

container with a content type of message/rfc822.

27498

The Parser constructor's strict argument was

27499

added, and its parse() and parsestr() methods

27500

grew a headersonly argument. The strict flag was

27501

also added to functions email.message_from_file()

27502

and email.message_from_string().

27503

Generator.__call__() is deprecated; use

27504

Generator.flatten() instead. The Generator

27505

class has also grown the clone() method.

27506

The DecodedGenerator class in the

27507

email.Generator module was added.

27508

The intermediate base classes MIMENonMultipart and

27509

MIMEMultipart have been added, and interposed in the

27510

class hierarchy for most of the other MIME-related derived

27511

classes.

27512

The _encoder argument to the MIMEText constructor

27513

has been deprecated. Encoding now happens implicitly based

27514

on the _charset argument.

27515

The following functions in the email.Utils module have

27516

been deprecated: dump_address_pairs(),

27517

decode(), and encode(). The following

27518

functions have been added to the module:

27519

make_msgid(), decode_rfc2231(),

27520

encode_rfc2231(), and decode_params().

27521

The non-public function email.Iterators._structure()

27522

was added.

27523

</description>

27524

</group>

27525

27526

<description>The email package was originally prototyped as a separate

27527

library called

27528

mimelib{http://mimelib.sf.net/}.

27529

Changes have been made so that

27530

method names are more consistent, and some methods or modules have

27531

either been added or removed. The semantics of some of the methods

27532

have also changed. For the most part, any functionality available in

27533

mimelib is still available in the email package,

27534

albeit often in a different way. Backward compatibility between

27535

the mimelib package and the email package was not a

27536

priority.

27537

Here is a brief description of the differences between the

27538

mimelib and the email packages, along with hints on

27539

how to port your applications.

27540

Of course, the most visible difference between the two packages is

27541

that the package name has been changed to email. In

27542

addition, the top-level package has the following differences:

27543

messageFromString() has been renamed to

27544

message_from_string().

27545

messageFromFile() has been renamed to

27546

message_from_file().

27547

The Message class has the following differences:

27548

The method asString() was renamed to as_string().

27549

The method ismultipart() was renamed to

27550

is_multipart().

27551

The get_payload() method has grown a decode

27552

optional argument.

27553

The method getall() was renamed to get_all().

27554

The method addheader() was renamed to add_header().

27555

The method gettype() was renamed to get_type().

27556

The methodgetmaintype() was renamed to

27557

get_main_type().

27558

The method getsubtype() was renamed to

27559

get_subtype().

27560

The method getparams() was renamed to

27561

get_params().

27562

Also, whereas getparams() returned a list of strings,

27563

get_params() returns a list of 2-tuples, effectively

27564

the key/value pairs of the parameters, split on the =

27565

sign.

27566

The method getparam() was renamed to get_param().

27567

The method getcharsets() was renamed to

27568

get_charsets().

27569

The method getfilename() was renamed to

27570

get_filename().

27571

The method getboundary() was renamed to

27572

get_boundary().

27573

The method setboundary() was renamed to

27574

set_boundary().

27575

The method getdecodedpayload() was removed. To get

27576

similar functionality, pass the value 1 to the decode flag

27577

of the {get_payload()} method.

27578

The method getpayloadastext() was removed. Similar

27579

functionality

27580

is supported by the DecodedGenerator class in the

27581

email.Generator module.

27582

The method getbodyastext() was removed. You can get

27583

similar functionality by creating an iterator with

27584

typed_subpart_iterator() in the

27585

email.Iterators module.

27586

The Parser class has no differences in its public interface.

27587

It does have some additional smarts to recognize

27588

message/delivery-status type messages, which it represents as

27589

a Message instance containing separate Message

27590

subparts for each header block in the delivery status

27591

notificationDelivery Status Notifications (DSN) are defined

27592

in 1894..

27593

The Generator class has no differences in its public

27594

interface. There is a new class in the email.Generator

27595

module though, called DecodedGenerator which provides most of

27596

the functionality previously available in the

27597

Message.getpayloadastext() method.

27598

The following modules and classes have been changed:

27599

The MIMEBase class constructor arguments _major

27600

and _minor have changed to _maintype and

27601

_subtype respectively.

27602

The Image class/module has been renamed to

27603

MIMEImage. The _minor argument has been renamed to

27604

_subtype.

27605

The Text class/module has been renamed to

27606

MIMEText. The _minor argument has been renamed to

27607

_subtype.

27608

The MessageRFC822 class/module has been renamed to

27609

MIMEMessage. Note that an earlier version of

27610

mimelib called this class/module RFC822, but

27611

that clashed with the Python standard library module

27612

rfc822 on some case-insensitive file systems.

27613

Also, the MIMEMessage class now represents any kind of

27614

MIME message with main type message. It takes an

27615

optional argument _subtype which is used to set the MIME

27616

subtype. _subtype defaults to rfc822.

27617

mimelib provided some utility functions in its

27618

address and date modules. All of these functions

27619

have been moved to the email.Utils module.

27620

The MsgReader class/module has been removed. Its functionality

27621

is most closely supported in the body_line_iterator()

27622

function in the email.Iterators module.

27623

</description>

27624

</group>

27625

27626

</group>

27627

</group>

27628

27629

<description>Mailcap file handling.

27630

Mailcap files are used to configure how MIME-aware applications such

27631

as mail readers and Web browsers react to files with different MIME

27632

types. (The name ``mailcap'' is derived from the phrase ``mail

27633

capability''.) For example, a mailcap file might contain a line like

27634

video/mpeg; xmpeg . Then, if the user encounters an email

27635

message or Web document with the MIME type video/mpeg,

27636

will be replaced by a filename (usually one belonging to a

27637

temporary file) and the xmpeg program can be automatically

27638

started to view the file.

27639

The mailcap format is documented in 1524, ``A User Agent

27640

Configuration Mechanism For Multimedia Mail Format Information,'' but

27641

is not an Internet standard. However, mailcap files are supported on

27642

most systems.

27643

</description>

27644

27645

<description>Return a 2-tuple; the first element is a string containing the command

27646

line to be executed

27647

(which can be passed to os.system()), and the second element is

27648

the mailcap entry for a given MIME type. If no matching MIME

27649

type can be found, (None, None) is returned.

27650

key is the name of the field desired, which represents the type

27651

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

27652

data. Other possible values might be 'compose' and 'edit', if you

27653

wanted to create a new body of the given MIME type or alter the

27654

existing body data. See 1524 for a complete list of these

27655

fields.

27656

filename is the filename to be substituted for in the

27657

command line; the default value is

27658

'/dev/null' which is almost certainly not what you want, so

27659

usually you'll override it by specifying a filename.

27660

plist can be a list containing named parameters; the default

27661

value is simply an empty list. Each entry in the list must be a

27662

string containing the parameter name, an equals sign (=),

27663

and the parameter's value. Mailcap entries can contain named parameters like %{foo}, which will be replaced by the

27664

value of the parameter named 'foo'. For example, if the command line

27665

showpartial %{id}{number}{total}

27666

was in a mailcap file, and plist was set to ['id=1',

27667

'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

27668

test some external condition (such as the machine architecture, or the

27669

window system in use) to determine whether or not the mailcap line

27670

applies. findmatch() will automatically check such

27671

conditions and skip the entry if the check fails.</description>

27672

<param name="caps" optional="0">caps</param><param name="MIMEtype%" optional="0">MIMEtype%</param><param name="key" optional="1">key</param><param name="filename" optional="1">filename</param><param name="plist" optional="1">plist</param>

27673

<insert>findmatch(caps, MIMEtype%, [key], [filename], [plist])</insert><dialog title="Insert findmatch">findmatch(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

27674

27675

27676

<description>Returns a dictionary mapping MIME types to a list of mailcap file

27677

entries. This dictionary must be passed to the findmatch()

27678

function. An entry is stored as a list of dictionaries, but it

27679

shouldn't be necessary to know the details of this representation.

27680

The information is derived from all of the mailcap files found on the

27681

system. Settings in the user's mailcap file /.mailcap

27682

will override settings in the system mailcap files

27683

/etc/mailcap, /usr/etc/mailcap, and

27684

/usr/local/etc/mailcap.</description>

27685

27686

<insert>getcaps()</insert><dialog title="Insert getcaps">getcaps()</dialog><info title="Info window"></info></function>

27687

27688

</group>

27689

27690

<description>Read various mailbox formats.

27691

This module defines a number of classes that allow easy and uniform

27692

access to mail messages in a () mailbox.

27693

</description>

27694

27695

<description>Access to a classic -style mailbox, where all messages are

27696

contained in a single file and separated by From (a.k.a. From_) lines. The file object fp points to the

27697

mailbox file. The optional factory parameter is a callable that

27698

should create new message objects. factory is called with one

27699

argument, fp by the next() method of the mailbox

27700

object. The default is the rfc822.Message class (see the

27701

rfc822 module -- and the note below).

27702

For maximum portability, messages in a -style mailbox are

27703

separated by any line that begins exactly with the string 'From

27704

' (note the trailing space) if preceded by exactly two newlines.

27705

Because of the wide-range of variations in practice, nothing else on

27706

the From_ line should be considered. However, the current

27707

implementation doesn't check for the leading two newlines. This is

27708

usually fine for most applications.

27709

The UnixMailbox class implements a more strict version of

27710

From_ line checking, using a regular expression that usually correctly

27711

matched From_ delimiters. It considers delimiter line to be separated

27712

by From name time lines. For maximum portability,

27713

use the PortableUnixMailbox class instead. This class is

27714

identical to UnixMailbox except that individual messages are

27715

separated by only From lines.

27716

For more information, see

27717

Configuring

27718

Netscape Mail on : Why the Content-Length Format is Bad.</description>

27719

<param name="fp" optional="0">fp</param><param name="factory" optional="1">factory</param>

27720

<insert>UnixMailbox(fp, [factory])</insert><dialog title="Insert UnixMailbox">UnixMailbox(%0, %1)</dialog><info title="Info window"></info></function>

27721

27722

27723

<description>A less-strict version of UnixMailbox, which considers only the

27724

From at the beginning of the line separating messages. The

27725

``name time'' portion of the From line is ignored, to

27726

protect against some variations that are observed in practice. This

27727

works since lines in the message which begin with 'From ' are

27728

quoted by mail handling software at delivery-time.</description>

27729

<param name="fp" optional="0">fp</param><param name="factory" optional="1">factory</param>

27730

<insert>PortableUnixMailbox(fp, [factory])</insert><dialog title="Insert PortableUnixMailbox">PortableUnixMailbox(%0, %1)</dialog><info title="Info window"></info></function>

27731

27732

27733

<description>Access an MMDF-style mailbox, where all messages are contained

27734

in a single file and separated by lines consisting of 4 control-A

27735

characters. The file object fp points to the mailbox file.

27736

Optional factory is as with the UnixMailbox class.</description>

27737

<param name="fp" optional="0">fp</param><param name="factory" optional="1">factory</param>

27738

<insert>MmdfMailbox(fp, [factory])</insert><dialog title="Insert MmdfMailbox">MmdfMailbox(%0, %1)</dialog><info title="Info window"></info></function>

27739

27740

27741

<description>Access an MH mailbox, a directory with each message in a separate

27742

file with a numeric name.

27743

The name of the mailbox directory is passed in dirname.

27744

factory is as with the UnixMailbox class.</description>

27745

<param name="dirname" optional="0">dirname</param><param name="factory" optional="1">factory</param>

27746

<insert>MHMailbox(dirname, [factory])</insert><dialog title="Insert MHMailbox">MHMailbox(%0, %1)</dialog><info title="Info window"></info></function>

27747

27748

27749

<description>Access a Qmail mail directory. All new and current mail for the

27750

mailbox specified by dirname is made available.

27751

factory is as with the UnixMailbox class.</description>

27752

<param name="dirname" optional="0">dirname</param><param name="factory" optional="1">factory</param>

27753

<insert>Maildir(dirname, [factory])</insert><dialog title="Insert Maildir">Maildir(%0, %1)</dialog><info title="Info window"></info></function>

27754

27755

27756

<description>Access a Babyl mailbox, which is similar to an MMDF mailbox. In

27757

Babyl format, each message has two sets of headers, the

27758

original headers and the visible headers. The original

27759

headers appear before a line containing only '*** EOOH ***'

27760

(End-Of-Original-Headers) and the visible headers appear after the

27761

EOOH line. Babyl-compliant mail readers will show you only the

27762

visible headers, and BabylMailbox objects will return messages

27763

containing only the visible headers. You'll have to do your own

27764

parsing of the mailbox file to get at the original headers. Mail

27765

messages start with the EOOH line and end with a line containing only

27766

'037014'. factory is as with the

27767

UnixMailbox class.</description>

27768

<param name="fp" optional="0">fp</param><param name="factory" optional="1">factory</param>

27769

<insert>BabylMailbox(fp, [factory])</insert><dialog title="Insert BabylMailbox">BabylMailbox(%0, %1)</dialog><info title="Info window"></info></function>

27770

27771

27772

<description>All implementations of mailbox objects are iterable objects, and

27773

have one externally visible method. This method is used by iterators

27774

created from mailbox objects and may also be used directly.

27775

</description>

27776

27777

<description>Return the next message in the mailbox, created with the optional

27778

factory argument passed into the mailbox object's constructor.

27779

By default this is an rfc822.Message

27780

object (see the rfc822 module). Depending on the mailbox

27781

implementation the fp attribute of this object may be a true

27782

file object or a class instance simulating a file object, taking care

27783

of things like message boundaries if multiple mail messages are

27784

contained in a single file, etc. If no more messages are available,

27785

this method returns None.</description>

27786

27787

27788

27789

</group>

27790

</group>

27791

27792

<description>% LaTeX'ized from the comments in the module by Skip Montanaro

27793

% <skip@mojam.com>.

27794

Manipulate MH mailboxes from Python.

27795

The mhlib module provides a Python interface to MH folders and

27796

their contents.

27797

The module contains three basic classes, MH, which represents a

27798

particular collection of folders, Folder, which represents a single

27799

folder, and Message, which represents a single message.

27800

</description>

27801

27802

<description>MH represents a collection of MH folders.</description>

27803

<param name="path" optional="0">path</param><param name="profile" optional="1">profile</param>

27804

<insert>MH(path, [profile])</insert><dialog title="Insert MH">MH(%0, %1)</dialog><info title="Info window"></info></function>

27805

27806

27807

<description>The Folder class represents a single folder and its messages.</description>

27808

27809

<insert>Folder(mh, name name)</insert><dialog title="Insert Folder">Folder(%0, %1)</dialog><info title="Info window"></info></function>

27810

27811

27812

<description>Message objects represent individual messages in a folder. The

27813

Message class is derived from mimetools.Message.</description>

27814

<param name="folder" optional="0">folder</param><param name="number" optional="0">number</param><param name="name" optional="1">name</param>

27815

<insert>Message(folder, number, [name])</insert><dialog title="Insert Message">Message(%0, %1, %2)</dialog><info title="Info window"></info></function>

27816

27817

27818

<description>MH instances have the following methods:

27819

</description>

27820

27821

<description>Print an error message -- can be overridden.</description>

27822

<param name="format" optional="0">format</param><param name="..." optional="1">...</param>

27823

<insert>error(format, [...])</insert><dialog title="Insert error">error(%0, %1)</dialog><info title="Info window"></info></function>

27824

27825

27826

<description>Return a profile entry (None if not set).</description>

27827

<param name="keykey" optional="0">keykey</param>

27828

<insert>getprofile(keykey)</insert><dialog title="Insert getprofile">getprofile(%0)</dialog><info title="Info window"></info></function>

27829

27830

27831

<description>Return the mailbox pathname.</description>

27832

27833

<insert>getpath()</insert><dialog title="Insert getpath">getpath()</dialog><info title="Info window"></info></function>

27834

27835

27836

<description>Return the current folder name.</description>

27837

27838

<insert>getcontext()</insert><dialog title="Insert getcontext">getcontext()</dialog><info title="Info window"></info></function>

27839

27840

27841

<description>Set the current folder name.</description>

27842

<param name="namename" optional="0">namename</param>

27843

<insert>setcontext(namename)</insert><dialog title="Insert setcontext">setcontext(%0)</dialog><info title="Info window"></info></function>

27844

27845

27846

<description>Return a list of top-level folders.</description>

27847

27848

<insert>listfolders()</insert><dialog title="Insert listfolders">listfolders()</dialog><info title="Info window"></info></function>

27849

27850

27851

<description>Return a list of all folders.</description>

27852

27853

<insert>listallfolders()</insert><dialog title="Insert listallfolders">listallfolders()</dialog><info title="Info window"></info></function>

27854

27855

27856

<description>Return a list of direct subfolders of the given folder.</description>

27857

<param name="namename" optional="0">namename</param>

27858

<insert>listsubfolders(namename)</insert><dialog title="Insert listsubfolders">listsubfolders(%0)</dialog><info title="Info window"></info></function>

27859

27860

27861

<description>Return a list of all subfolders of the given folder.</description>

27862

<param name="namename" optional="0">namename</param>

27863

<insert>listallsubfolders(namename)</insert><dialog title="Insert listallsubfolders">listallsubfolders(%0)</dialog><info title="Info window"></info></function>

27864

27865

27866

<description>Create a new folder.</description>

27867

<param name="namename" optional="0">namename</param>

27868

<insert>makefolder(namename)</insert><dialog title="Insert makefolder">makefolder(%0)</dialog><info title="Info window"></info></function>

27869

27870

27871

<description>Delete a folder -- must have no subfolders.</description>

27872

<param name="namename" optional="0">namename</param>

27873

<insert>deletefolder(namename)</insert><dialog title="Insert deletefolder">deletefolder(%0)</dialog><info title="Info window"></info></function>

27874

27875

27876

<description>Return a new open folder object.</description>

27877

<param name="namename" optional="0">namename</param>

27878

<insert>openfolder(namename)</insert><dialog title="Insert openfolder">openfolder(%0)</dialog><info title="Info window"></info></function>

27879

27880

</group>

27881

27882

<description>Folder instances represent open folders and have the following

27883

methods:

27884

</description>

27885

27886

<description>Print an error message -- can be overridden.</description>

27887

<param name="format" optional="0">format</param><param name="..." optional="1">...</param>

27888

<insert>error(format, [...])</insert><dialog title="Insert error">error(%0, %1)</dialog><info title="Info window"></info></function>

27889

27890

27891

<description>Return the folder's full pathname.</description>

27892

27893

<insert>getfullname()</insert><dialog title="Insert getfullname">getfullname()</dialog><info title="Info window"></info></function>

27894

27895

27896

<description>Return the full pathname of the folder's sequences file.</description>

27897

27898

<insert>getsequencesfilename()</insert><dialog title="Insert getsequencesfilename">getsequencesfilename()</dialog><info title="Info window"></info></function>

27899

27900

27901

<description>Return the full pathname of message n of the folder.</description>

27902

27903

<insert>getmessagefilename(nn)</insert><dialog title="Insert getmessagefilename">getmessagefilename(%0)</dialog><info title="Info window"></info></function>

27904

27905

27906

<description>Return a list of messages in the folder (as numbers).</description>

27907

27908

<insert>listmessages()</insert><dialog title="Insert listmessages">listmessages()</dialog><info title="Info window"></info></function>

27909

27910

27911

<description>Return the current message number.</description>

27912

27913

<insert>getcurrent()</insert><dialog title="Insert getcurrent">getcurrent()</dialog><info title="Info window"></info></function>

27914

27915

27916

<description>Set the current message number to n.</description>

27917

27918

<insert>setcurrent(nn)</insert><dialog title="Insert setcurrent">setcurrent(%0)</dialog><info title="Info window"></info></function>

27919

27920

27921

<description>Parse msgs syntax into list of messages.</description>

27922

<param name="seqseq" optional="0">seqseq</param>

27923

<insert>parsesequence(seqseq)</insert><dialog title="Insert parsesequence">parsesequence(%0)</dialog><info title="Info window"></info></function>

27924

27925

27926

<description>Get last message, or 0 if no messages are in the folder.</description>

27927

27928

<insert>getlast()</insert><dialog title="Insert getlast">getlast()</dialog><info title="Info window"></info></function>

27929

27930

27931

<description>Set last message (internal use only).</description>

27932

27933

<insert>setlast(nn)</insert><dialog title="Insert setlast">setlast(%0)</dialog><info title="Info window"></info></function>

27934

27935

27936

<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

27937

sequences.</description>

27938

27939

<insert>getsequences()</insert><dialog title="Insert getsequences">getsequences()</dialog><info title="Info window"></info></function>

27940

27941

27942

<description>Return dictionary of sequences in folder {name: list}.</description>

27943

<param name="dictdict" optional="0">dictdict</param>

27944

<insert>putsequences(dictdict)</insert><dialog title="Insert putsequences">putsequences(%0)</dialog><info title="Info window"></info></function>

27945

27946

27947

<description>Remove messages in list from folder.</description>

27948

<param name="listlist" optional="0">listlist</param>

27949

<insert>removemessages(listlist)</insert><dialog title="Insert removemessages">removemessages(%0)</dialog><info title="Info window"></info></function>

27950

27951

27952

<description>Move messages in list to other folder.</description>

27953

<param name="list" optional="0">list</param><param name="tofolder tofolder" optional="0">tofolder tofolder</param>

27954

<insert>refilemessages(list, tofolder tofolder)</insert><dialog title="Insert refilemessages">refilemessages(%0, %1)</dialog><info title="Info window"></info></function>

27955

27956

27957

<description>Move one message to a given destination in another folder.</description>

27958

<param name="n" optional="0">n</param><param name="tofolder" optional="0">tofolder</param><param name="ton ton" optional="0">ton ton</param>

27959

<insert>movemessage(n, tofolder, ton ton)</insert><dialog title="Insert movemessage">movemessage(%0, %1, %2)</dialog><info title="Info window"></info></function>

27960

27961

27962

<description>Copy one message to a given destination in another folder.</description>

27963

<param name="n" optional="0">n</param><param name="tofolder" optional="0">tofolder</param><param name="ton ton" optional="0">ton ton</param>

27964

<insert>copymessage(n, tofolder, ton ton)</insert><dialog title="Insert copymessage">copymessage(%0, %1, %2)</dialog><info title="Info window"></info></function>

27965

27966

</group>

27967

27968

<description>The Message class adds one method to those of

27969

mimetools.Message:

27970

</description>

27971

27972

<description>Return a new open message object (costs a file descriptor).</description>

27973

27974

<insert>openmessage(nn)</insert><dialog title="Insert openmessage">openmessage(%0)</dialog><info title="Info window"></info></function>

27975

27976

</group>

27977

</group>

27978

27979

<description>Tools for parsing MIME-style message bodies.

27980

2.3{The email package should be used in

27981

preference to the mimetools module. This

27982

module is present only to maintain backward

27983

compatibility.}

27984

This module defines a subclass of the

27985

rfc822rfc822 module's

27986

Message class and a number of utility functions that are

27987

useful for the manipulation for MIME multipart or encoded message.

27988

It defines the following items:

27989

</description>

27990

27991

<description>Return a new instance of the Message class. This is a

27992

subclass of the rfc822.Message class, with some additional

27993

methods (see below). The seekable argument has the same meaning

27994

as for rfc822.Message.</description>

27995

<param name="fp" optional="0">fp</param><param name="seekable" optional="1">seekable</param>

27996

<insert>Message(fp, [seekable])</insert><dialog title="Insert Message">Message(%0, %1)</dialog><info title="Info window"></info></function>

27997

27998

27999

<description>Return a unique string that has a high likelihood of being usable as a

28000

part boundary. The string has the form

28001

'hostipaddr.uid.pid.timestamp.random'.</description>

28002

28003

<insert>choose_boundary()</insert><dialog title="Insert choose_boundary">choose_boundary()</dialog><info title="Info window"></info></function>

28004

28005

28006

<description>Read data encoded using the allowed MIME encoding from open file

28007

object input and write the decoded data to open file object

28008

output. Valid values for encoding include

28009

'base64', 'quoted-printable', 'uuencode',

28010

'x-uuencode', 'uue', 'x-uue', '7bit', and '8bit'. Decoding messages encoded in '7bit' or '8bit'

28011

has no effect. The input is simply copied to the output.</description>

28012

<param name="input" optional="0">input</param><param name="output" optional="0">output</param><param name="encoding encoding" optional="0">encoding encoding</param>

28013

<insert>decode(input, output, encoding encoding)</insert><dialog title="Insert decode">decode(%0, %1, %2)</dialog><info title="Info window"></info></function>

28014

28015

28016

<description>Read data from open file object input and write it encoded using

28017

the allowed MIME encoding to open file object output.

28018

Valid values for encoding are the same as for decode().</description>

28019

<param name="input" optional="0">input</param><param name="output" optional="0">output</param><param name="encoding encoding" optional="0">encoding encoding</param>

28020

<insert>encode(input, output, encoding encoding)</insert><dialog title="Insert encode">encode(%0, %1, %2)</dialog><info title="Info window"></info></function>

28021

28022

28023

<description>Read lines from open file input until and write them to

28024

open file output.</description>

28025

<param name="input" optional="0">input</param><param name="output output" optional="0">output output</param>

28026

<insert>copyliteral(input, output output)</insert><dialog title="Insert copyliteral">copyliteral(%0, %1)</dialog><info title="Info window"></info></function>

28027

28028

28029

<description>Read blocks until from open file input and write them to

28030

open file output. The block size is currently fixed at 8192.</description>

28031

<param name="input" optional="0">input</param><param name="output output" optional="0">output output</param>

28032

<insert>copybinary(input, output output)</insert><dialog title="Insert copybinary">copybinary(%0, %1)</dialog><info title="Info window"></info></function>

28033

28034

28035

<description>The Message class defines the following methods in

28036

addition to the rfc822.Message methods:

28037

</description>

28038

28039

<description>Return the parameter list of the Content-Type header.

28040

This is a list of strings. For parameters of the form

28041

key=value, key is converted to lower case but

28042

value is not. For example, if the message contains the header

28043

Content-type: text/html; spam=1; Spam=2; Spam then

28044

getplist() will return the Python list ['spam=1',

28045

'spam=2', 'Spam'].</description>

28046

28047

<insert>getplist()</insert><dialog title="Insert getplist">getplist()</dialog><info title="Info window"></info></function>

28048

28049

28050

<description>Return the value of the first parameter (as returned by

28051

getplist()) of the form name=value for the

28052

given name. If value is surrounded by quotes of the form

28053

`<...>' or `"..."', these are removed.</description>

28054

<param name="namename" optional="0">namename</param>

28055

<insert>getparam(namename)</insert><dialog title="Insert getparam">getparam(%0)</dialog><info title="Info window"></info></function>

28056

28057

28058

<description>Return the encoding specified in the

28059

Content-Transfer-Encoding message header. If no such

28060

header exists, return '7bit'. The encoding is converted to

28061

lower case.</description>

28062

28063

<insert>getencoding()</insert><dialog title="Insert getencoding">getencoding()</dialog><info title="Info window"></info></function>

28064

28065

28066

<description>Return the message type (of the form type/subtype)

28067

as specified in the Content-Type header. If no such

28068

header exists, return 'text/plain'. The type is converted to

28069

lower case.</description>

28070

28071

<insert>gettype()</insert><dialog title="Insert gettype">gettype()</dialog><info title="Info window"></info></function>

28072

28073

28074

<description>Return the main type as specified in the Content-Type

28075

header. If no such header exists, return 'text'. The main

28076

type is converted to lower case.</description>

28077

28078

<insert>getmaintype()</insert><dialog title="Insert getmaintype">getmaintype()</dialog><info title="Info window"></info></function>

28079

28080

28081

<description>Return the subtype as specified in the Content-Type

28082

header. If no such header exists, return 'plain'. The subtype

28083

is converted to lower case.</description>

28084

28085

<insert>getsubtype()</insert><dialog title="Insert getsubtype">getsubtype()</dialog><info title="Info window"></info></function>

28086

28087

</group>

28088

</group>

28089

28090

<description>Mapping of filename extensions to MIME types.

28091

The mimetypes module converts between a filename or URL and

28092

the MIME type associated with the filename extension. Conversions are

28093

provided from filename to MIME type and from MIME type to filename

28094

extension; encodings are not supported for the latter conversion.

28095

The module provides one class and a number of convenience functions.

28096

The functions are the normal interface to this module, but some

28097

applications may be interested in the class as well.

28098

The functions described below provide the primary interface for this

28099

module. If the module has not been initialized, they will call

28100

init() if they rely on the information init()

28101

sets up.

28102

</description>

28103

28104

<description>Guess the type of a file based on its filename or URL, given by

28105

filename. The return value is a tuple (type,

28106

encoding) where type is None if the type can't be

28107

guessed (missing or unknown suffix) or a string of the form

28108

'type/subtype', usable for a MIME

28109

content-type header.

28110

encoding is None for no encoding or the name of the

28111

program used to encode (e.g. compress or gzip).

28112

The encoding is suitable for use as a Content-Encoding

28113

header, not as a Content-Transfer-Encoding header.

28114

The mappings are table driven. Encoding suffixes are case sensitive;

28115

type suffixes are first tried case sensitively, then case

28116

insensitively.

28117

Optional strict is a flag specifying whether the list of known

28118

MIME types is limited to only the official types registered

28119

with IANA{http://www.isi.edu/in-notes/iana/assignments/media-types}

28120

are recognized. When strict is true (the default), only the

28121

IANA types are supported; when strict is false, some additional

28122

non-standard but commonly used MIME types are also recognized.</description>

28123

<param name="filename" optional="0">filename</param><param name="strict" optional="1">strict</param>

28124

<insert>guess_type(filename, [strict])</insert><dialog title="Insert guess_type">guess_type(%0, %1)</dialog><info title="Info window"></info></function>

28125

28126

28127

<description>Guess the extensions for a file based on its MIME type, given by

28128

type.

28129

The return value is a list of strings giving all possible filename extensions,

28130

including the leading dot (.). The extensions are not guaranteed

28131

to have been associated with any particular data stream, but would be mapped

28132

to the MIME type type by guess_type().

28133

Optional strict has the same meaning as with the

28134

guess_type() function.</description>

28135

<param name="type" optional="0">type</param><param name="strict" optional="1">strict</param>

28136

<insert>guess_all_extensions(type, [strict])</insert><dialog title="Insert guess_all_extensions">guess_all_extensions(%0, %1)</dialog><info title="Info window"></info></function>

28137

28138

28139

<description>Guess the extension for a file based on its MIME type, given by

28140

type.

28141

The return value is a string giving a filename extension, including the

28142

leading dot (.). The extension is not guaranteed to have been

28143

associated with any particular data stream, but would be mapped to the MIME type type by guess_type(). If no extension can

28144

be guessed for type, None is returned.

28145

Optional strict has the same meaning as with the

28146

guess_type() function.</description>

28147

<param name="type" optional="0">type</param><param name="strict" optional="1">strict</param>

28148

<insert>guess_extension(type, [strict])</insert><dialog title="Insert guess_extension">guess_extension(%0, %1)</dialog><info title="Info window"></info></function>

28149

28150

28151

<description>Initialize the internal data structures. If given, files must

28152

be a sequence of file names which should be used to augment the

28153

default type map. If omitted, the file names to use are taken from

28154

knownfiles. Each file named in files or

28155

knownfiles takes precedence over those named before it.

28156

Calling init() repeatedly is allowed.</description>

28157

<param name="files" optional="0">files</param>

28158

<insert>init(files)</insert><dialog title="Insert init">init(%0)</dialog><info title="Info window"></info></function>

28159

28160

28161

<description>Load the type map given in the file filename, if it exists. The type map is returned as a dictionary mapping filename extensions,

28162

including the leading dot (.), to strings of the form

28163

'type/subtype'. If the file filename does

28164

not exist or cannot be read, None is returned.</description>

28165

<param name="filenamefilename" optional="0">filenamefilename</param>

28166

<insert>read_mime_types(filenamefilename)</insert><dialog title="Insert read_mime_types">read_mime_types(%0)</dialog><info title="Info window"></info></function>

28167

28168

28169

<description>Add a mapping from the mimetype type to the extension ext.

28170

When the extension is already known, the new type will replace the old

28171

one. When the type is already known the extension will be added

28172

to the list of known extensions.

28173

When strict is the mapping will added to the official

28174

MIME types, otherwise to the non-standard ones.</description>

28175

<param name="type" optional="0">type</param><param name="ext" optional="0">ext</param><param name="strict" optional="1">strict</param>

28176

<insert>add_type(type, ext, [strict])</insert><dialog title="Insert add_type">add_type(%0, %1, %2)</dialog><info title="Info window"></info></function>

28177

28178

28179

<description>This class represents a MIME-types database. By default, it

28180

provides access to the same database as the rest of this module.

28181

The initial database is a copy of that provided by the module, and

28182

may be extended by loading additional mime.types-style files

28183

into the database using the read() or readfp()

28184

methods. The mapping dictionaries may also be cleared before

28185

loading additional data if the default data is not desired.

28186

The optional filenames parameter can be used to cause

28187

additional files to be loaded ``on top'' of the default database.

28188

New in version 2.2</description>

28189

<param name="filenames" optional="0">filenames</param>

28190

<insert>MimeTypes(filenames)</insert><dialog title="Insert MimeTypes">MimeTypes(%0)</dialog><info title="Info window"></info></function>

28191

28192

28193

<description>MimeTypes instances provide an interface which is very like

28194

that of the mimetypes module.

28195

{suffix_map}

28196

Dictionary mapping suffixes to suffixes. This is used to allow

28197

recognition of encoded files for which the encoding and the type are

28198

indicated by the same extension. For example, the .tgz

28199

extension is mapped to .tar.gz to allow the encoding and type

28200

to be recognized separately. This is initially a copy of the global

28201

suffix_map defined in the module.

28202

{encodings_map}

28203

Dictionary mapping filename extensions to encoding types. This is

28204

initially a copy of the global encodings_map defined in the

28205

module.

28206

{types_map}

28207

Dictionary mapping filename extensions to MIME types. This is

28208

initially a copy of the global types_map defined in the

28209

module.

28210

{common_types}

28211

Dictionary mapping filename extensions to non-standard, but commonly

28212

found MIME types. This is initially a copy of the global

28213

common_types defined in the module.

28214

</description>

28215

28216

<description>Similar to the guess_extension() function, using the

28217

tables stored as part of the object.</description>

28218

<param name="type" optional="0">type</param><param name="strict" optional="1">strict</param>

28219

<insert>guess_extension(type, [strict])</insert><dialog title="Insert guess_extension">guess_extension(%0, %1)</dialog><info title="Info window"></info></function>

28220

28221

28222

<description>Similar to the guess_type() function, using the tables

28223

stored as part of the object.</description>

28224

<param name="url" optional="0">url</param><param name="strict" optional="1">strict</param>

28225

<insert>guess_type(url, [strict])</insert><dialog title="Insert guess_type">guess_type(%0, %1)</dialog><info title="Info window"></info></function>

28226

28227

28228

<description>Load MIME information from a file named path. This uses

28229

readfp() to parse the file.</description>

28230

<param name="pathpath" optional="0">pathpath</param>

28231

<insert>read(pathpath)</insert><dialog title="Insert read">read(%0)</dialog><info title="Info window"></info></function>

28232

28233

28234

<description>Load MIME type information from an open file. The file must have

28235

the format of the standard mime.types files.</description>

28236

<param name="filefile" optional="0">filefile</param>

28237

<insert>readfp(filefile)</insert><dialog title="Insert readfp">readfp(%0)</dialog><info title="Info window"></info></function>

28238

28239

</group>

28240

</group>

28241

28242

<description>Generic MIME file writer.

28243

2.3{The email package should be used in

28244

preference to the MimeWriter module. This

28245

module is present only to maintain backward

28246

compatibility.}

28247

This module defines the class MimeWriter. The

28248

MimeWriter class implements a basic formatter for creating

28249

MIME multi-part files. It doesn't seek around the output file nor

28250

does it use large amounts of buffer space. You must write the parts

28251

out in the order that they should occur in the final

28252

file. MimeWriter does buffer the headers you add, allowing you to rearrange their order.

28253

</description>

28254

28255

<description>Return a new instance of the MimeWriter class. The only

28256

argument passed, fp, is a file object to be used for

28257

writing. Note that a StringIO object could also be used.</description>

28258

28259

<insert>MimeWriter(fpfp)</insert><dialog title="Insert MimeWriter">MimeWriter(%0)</dialog><info title="Info window"></info></function>

28260

28261

28262

<description>MimeWriter instances have the following methods:

28263

</description>

28264

28265

<description>Add a header line to the MIME message. The key is the name of

28266

the header, where the value obviously provides the value of the

28267

header. The optional argument prefix determines where the header is inserted; 0 means append at the end, 1 is insert at

28268

the start. The default is to append.</description>

28269

<param name="key" optional="0">key</param><param name="value" optional="0">value</param><param name="prefix" optional="1">prefix</param>

28270

<insert>addheader(key, value, [prefix])</insert><dialog title="Insert addheader">addheader(%0, %1, %2)</dialog><info title="Info window"></info></function>

28271

28272

28273

<description>Causes all headers accumulated so far to be written out (and

28274

forgotten). This is useful if you don't need a body part at all,

28275

e.g. a subpart of type message/rfc822 that's (mis)used

28276

to store some header-like information.</description>

28277

28278

<insert>flushheaders()</insert><dialog title="Insert flushheaders">flushheaders()</dialog><info title="Info window"></info></function>

28279

28280

28281

<description>Returns a file-like object which can be used to write to the

28282

body of the message. The content-type is set to the provided

28283

ctype, and the optional parameter plist provides

28284

additional parameters for the content-type declaration. prefix

28285

functions as in addheader() except that the default is to

28286

insert at the start.</description>

28287

<param name="ctype" optional="0">ctype</param><param name="plist" optional="1">plist</param><param name="prefix" optional="1">prefix</param>

28288

<insert>startbody(ctype, [plist], [prefix])</insert><dialog title="Insert startbody">startbody(%0, %1, %2)</dialog><info title="Info window"></info></function>

28289

28290

28291

<description>Returns a file-like object which can be used to write to the

28292

body of the message. Additionally, this method initializes the

28293

multi-part code, where subtype provides the multipart subtype,

28294

boundary may provide a user-defined boundary specification, and

28295

plist provides optional parameters for the subtype.

28296

prefix functions as in startbody(). Subparts should be

28297

created using nextpart().</description>

28298

<param name="subtype" optional="0">subtype</param><param name="boundary" optional="1">boundary</param><param name="plist" optional="1">plist</param><param name="prefix" optional="1">prefix</param>

28299

<insert>startmultipartbody(subtype, [boundary], [plist], [prefix])</insert><dialog title="Insert startmultipartbody">startmultipartbody(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

28300

28301

28302

<description>Returns a new instance of MimeWriter which represents an

28303

individual part in a multipart message. This may be used to write the part as well as used for creating recursively complex multipart

28304

messages. The message must first be initialized with

28305

startmultipartbody() before using nextpart().</description>

28306

28307

<insert>nextpart()</insert><dialog title="Insert nextpart">nextpart()</dialog><info title="Info window"></info></function>

28308

28309

28310

<description>This is used to designate the last part of a multipart message, and

28311

should always be used when writing multipart messages.</description>

28312

28313

<insert>lastpart()</insert><dialog title="Insert lastpart">lastpart()</dialog><info title="Info window"></info></function>

28314

28315

</group>

28316

</group>

28317

28318

<description>Mimification and unmimification of mail messages.

28319

2.3{The email package should be used in

28320

preference to the mimify module. This

28321

module is present only to maintain backward

28322

compatibility.}

28323

The mimify module defines two functions to convert mail messages to

28324

and from MIME format. The mail message can be either a simple message

28325

or a so-called multipart message. Each part is treated separately.

28326

Mimifying (a part of) a message entails encoding the message as

28327

quoted-printable if it contains any characters that cannot be

28328

represented using 7-bit . Unmimifying (a part of) a message

28329

entails undoing the quoted-printable encoding. Mimify and unmimify

28330

are especially useful when a message has to be edited before being

28331

sent. Typical use would be:

28332

unmimify message

28333

edit message

28334

mimify message

28335

send message

28336

The modules defines the following user-callable functions and

28337

user-settable variables:

28338

</description>

28339

28340

<description>Copy the message in infile to outfile, converting parts to

28341

quoted-printable and adding MIME mail headers when necessary.

28342

infile and outfile can be file objects (actually, any

28343

object that has a readline() method (for infile) or a

28344

write() method (for outfile)) or strings naming the files.

28345

If infile and outfile are both strings, they may have the

28346

same value.</description>

28347

<param name="infile" optional="0">infile</param><param name="outfile outfile" optional="0">outfile outfile</param>

28348

<insert>mimify(infile, outfile outfile)</insert><dialog title="Insert mimify">mimify(%0, %1)</dialog><info title="Info window"></info></function>

28349

28350

28351

<description>Copy the message in infile to outfile, decoding all

28352

quoted-printable parts. infile and outfile can be file

28353

objects (actually, any object that has a readline() method (for

28354

infile) or a write() method (for outfile)) or strings

28355

naming the files. If infile and outfile are both strings,

28356

they may have the same value.

28357

If the decode_base64 argument is provided and tests true, any

28358

parts that are coded in the base64 encoding are decoded as well.</description>

28359

<param name="infile" optional="0">infile</param><param name="outfile" optional="0">outfile</param><param name="decode_base64" optional="1">decode_base64</param>

28360

<insert>unmimify(infile, outfile, [decode_base64])</insert><dialog title="Insert unmimify">unmimify(%0, %1, %2)</dialog><info title="Info window"></info></function>

28361

28362

28363

<description>Return a decoded version of the encoded header line in line.

28364

This only supports the ISO 8859-1 charset (Latin-1).</description>

28365

<param name="lineline" optional="0">lineline</param>

28366

<insert>mime_decode_header(lineline)</insert><dialog title="Insert mime_decode_header">mime_decode_header(%0)</dialog><info title="Info window"></info></function>

28367

28368

28369

<description>Return a MIME-encoded version of the header line in line.</description>

28370

<param name="lineline" optional="0">lineline</param>

28371

<insert>mime_encode_header(lineline)</insert><dialog title="Insert mime_encode_header">mime_encode_header(%0)</dialog><info title="Info window"></info></function>

28372

28373

</group>

28374

28375

<description>Support for reading files which contain distinct

28376

parts, such as some MIME data.

28377

The MultiFile object enables you to treat sections of a text

28378

file as file-like input objects, with '' being returned by

28379

readline() when a given delimiter pattern is encountered. The

28380

defaults of this class are designed to make it useful for parsing

28381

MIME multipart messages, but by subclassing it and overriding methods it can be easily adapted for more general use.

28382

</description>

28383

28384

<description>Create a multi-file. You must instantiate this class with an input

28385

object argument for the MultiFile instance to get lines from,

28386

such as a file object returned by open().

28387

MultiFile only ever looks at the input object's

28388

readline(), seek() and tell() methods, and

28389

the latter two are only needed if you want random access to the

28390

individual MIME parts. To use MultiFile on a non-seekable

28391

stream object, set the optional seekable argument to false; this

28392

will prevent using the input object's seek() and

28393

tell() methods.</description>

28394

<param name="fp" optional="0">fp</param><param name="seekable" optional="1">seekable</param>

28395

<insert>MultiFile(fp, [seekable])</insert><dialog title="Insert MultiFile">MultiFile(%0, %1)</dialog><info title="Info window"></info></function>

28396

28397

28398

<description>A MultiFile instance has the following methods:

28399

</description>

28400

28401

<description>Read a line. If the line is data (not a section-divider or end-marker

28402

or real EOF) return it. If the line matches the most-recently-stacked

28403

boundary, return '' and set self.last to 1 or 0 according as

28404

the match is or is not an end-marker. If the line matches any other

28405

stacked boundary, raise an error. On encountering end-of-file on the

28406

underlying stream object, the method raises Error unless

28407

all boundaries have been popped.</description>

28408

<param name="strstr" optional="0">strstr</param>

28409

<insert>readline(strstr)</insert><dialog title="Insert readline">readline(%0)</dialog><info title="Info window"></info></function>

28410

28411

28412

<description>Return all lines remaining in this part as a list of strings.</description>

28413

<param name="strstr" optional="0">strstr</param>

28414

<insert>readlines(strstr)</insert><dialog title="Insert readlines">readlines(%0)</dialog><info title="Info window"></info></function>

28415

28416

28417

<description>Read all lines, up to the next section. Return them as a single

28418

(multiline) string. Note that this doesn't take a size argument!</description>

28419

28420

28421

28422

28423

<description>Seek. Seek indices are relative to the start of the current section.

28424

The pos and whence arguments are interpreted as for a file

28425

seek.</description>

28426

<param name="pos" optional="0">pos</param><param name="whence" optional="1">whence</param>

28427

<insert>seek(pos, [whence])</insert><dialog title="Insert seek">seek(%0, %1)</dialog><info title="Info window"></info></function>

28428

28429

28430

<description>Return the file position relative to the start of the current section.</description>

28431

28432

28433

28434

28435

<description>Skip lines to the next section (that is, read lines until a

28436

section-divider or end-marker has been consumed). Return true if

28437

there is such a section, false if an end-marker is seen. Re-enable

28438

the most-recently-pushed boundary.</description>

28439

28440

28441

28442

28443

<description>Return true if str is data and false if it might be a section

28444

boundary. As written, it tests for a prefix other than '--' at

28445

start of line (which all MIME boundaries have) but it is declared so

28446

it can be overridden in derived classes.

28447

Note that this test is used intended as a fast guard for the real

28448

boundary tests; if it always returns false it will merely slow

28449

processing, not cause it to fail.</description>

28450

<param name="strstr" optional="0">strstr</param>

28451

<insert>is_data(strstr)</insert><dialog title="Insert is_data">is_data(%0)</dialog><info title="Info window"></info></function>

28452

28453

28454

<description>Push a boundary string. When an appropriately decorated version of

28455

this boundary is found as an input line, it will be interpreted as a

28456

section-divider or end-marker. All subsequent

28457

reads will return the empty string to indicate end-of-file, until a

28458

call to pop() removes the boundary a or next() call

28459

reenables it.

28460

It is possible to push more than one boundary. Encountering the

28461

most-recently-pushed boundary will return EOF; encountering any other

28462

boundary will raise an error.</description>

28463

<param name="strstr" optional="0">strstr</param>

28464

<insert>push(strstr)</insert><dialog title="Insert push">push(%0)</dialog><info title="Info window"></info></function>

28465

28466

28467

<description>Pop a section boundary. This boundary will no longer be interpreted

28468

as EOF.</description>

28469

28470

28471

28472

28473

<description>Turn a boundary into a section-divider line. By default, this

28474

method prepends '--' (which MIME section boundaries have) but

28475

it is declared so it can be overridden in derived classes. This

28476

method need not append LF or CR-LF, as comparison with the result

28477

ignores trailing whitespace.</description>

28478

<param name="strstr" optional="0">strstr</param>

28479

<insert>section_divider(strstr)</insert><dialog title="Insert section_divider">section_divider(%0)</dialog><info title="Info window"></info></function>

28480

28481

28482

<description>Turn a boundary string into an end-marker line. By default, this

28483

method prepends '--' and appends '--' (like a

28484

MIME-multipart end-of-message marker) but it is declared so it can be

28485

overridden in derived classes. This method need not append LF or

28486

CR-LF, as comparison with the result ignores trailing whitespace.</description>

28487

<param name="strstr" optional="0">strstr</param>

28488

<insert>end_marker(strstr)</insert><dialog title="Insert end_marker">end_marker(%0)</dialog><info title="Info window"></info></function>

28489

28490

</group>

28491

28492

</group>

28493

</group>

28494

28495

<description>Parse 2822 style mail messages.

28496

2.3{The email package should be used in

28497

preference to the rfc822 module. This

28498

module is present only to maintain backward

28499

compatibility.}

28500

This module defines a class, Message, which represents an

28501

``email message'' as defined by the Internet standard

28502

2822.This module originally conformed to 822,

28503

hence the name. Since then, 2822 has been released as an

28504

update to 822. This module should be considered

28505

2822-conformant, especially in cases where the

28506

syntax or semantics have changed since 822. Such messages

28507

consist of a collection of message headers, and a message body. This

28508

module also defines a helper class

28509

AddressList for parsing 2822 addresses. Please refer to

28510

the RFC for information on the specific syntax of 2822 messages.

28511

The mailboxmailbox module provides classes to read mailboxes produced by various end-user mail programs.

28512

</description>

28513

28514

<description>A Message instance is instantiated with an input object as

28515

parameter. Message relies only on the input object having a

28516

readline() method; in particular, ordinary file objects

28517

qualify. Instantiation reads headers from the input object up to a

28518

delimiter line (normally a blank line) and stores them in the

28519

instance. The message body, following the headers, is not consumed.

28520

This class can work with any input object that supports a

28521

readline() method. If the input object has seek and tell

28522

capability, the rewindbody() method will work; also, illegal

28523

lines will be pushed back onto the input stream. If the input object

28524

lacks seek but has an unread() method that can push back a

28525

line of input, Message will use that to push back illegal

28526

lines. Thus this class can be used to parse messages coming from a

28527

buffered stream.

28528

The optional seekable argument is provided as a workaround for

28529

certain stdio libraries in which tell() discards buffered

28530

data before discovering that the lseek() system call

28531

doesn't work. For maximum portability, you should set the seekable

28532

argument to zero to prevent that initial tell() when passing

28533

in an unseekable object such as a file object created from a socket

28534

object.

28535

Input lines as read from the file may either be terminated by CR-LF or

28536

by a single linefeed; a terminating CR-LF is replaced by a single

28537

linefeed before the line is stored.

28538

All header matching is done independent of upper or lower case;

28539

e.g. m['From'], m['from'] and

28540

m['FROM'] all yield the same result.</description>

28541

<param name="file" optional="0">file</param><param name="seekable" optional="1">seekable</param>

28542

<insert>Message(file, [seekable])</insert><dialog title="Insert Message">Message(%0, %1)</dialog><info title="Info window"></info></function>

28543

28544

28545

<description>You may instantiate the AddressList helper class using a single

28546

string parameter, a comma-separated list of 2822 addresses to be

28547

parsed. (The parameter None yields an empty list.)</description>

28548

<param name="fieldfield" optional="0">fieldfield</param>

28549

<insert>AddressList(fieldfield)</insert><dialog title="Insert AddressList">AddressList(%0)</dialog><info title="Info window"></info></function>

28550

28551

28552

<description>Return a new string with backslashes in str replaced by two

28553

backslashes and double quotes replaced by backslash-double quote.</description>

28554

<param name="strstr" optional="0">strstr</param>

28555

<insert>quote(strstr)</insert><dialog title="Insert quote">quote(%0)</dialog><info title="Info window"></info></function>

28556

28557

28558

<description>Return a new string which is an unquoted version of str.

28559

If str ends and begins with double quotes, they are stripped

28560

off. Likewise if str ends and begins with angle brackets, they

28561

are stripped off.</description>

28562

<param name="strstr" optional="0">strstr</param>

28563

<insert>unquote(strstr)</insert><dialog title="Insert unquote">unquote(%0)</dialog><info title="Info window"></info></function>

28564

28565

28566

<description>Parse address, which should be the value of some

28567

address-containing field such as To or Cc,

28568

into its constituent ``realname'' and ``email address'' parts.

28569

Returns a tuple of that information, unless the parse fails, in which

28570

case a 2-tuple (None, None) is returned.</description>

28571

<param name="addressaddress" optional="0">addressaddress</param>

28572

<insert>parseaddr(addressaddress)</insert><dialog title="Insert parseaddr">parseaddr(%0)</dialog><info title="Info window"></info></function>

28573

28574

28575

<description>The inverse of parseaddr(), this takes a 2-tuple of the form

28576

(realname, email_address) and returns the string

28577

value suitable for a To or Cc header. If

28578

the first element of pair is false, then the second element is

28579

returned unmodified.</description>

28580

<param name="pairpair" optional="0">pairpair</param>

28581

<insert>dump_address_pair(pairpair)</insert><dialog title="Insert dump_address_pair">dump_address_pair(%0)</dialog><info title="Info window"></info></function>

28582

28583

28584

<description>Attempts to parse a date according to the rules in 2822.

28585

however, some mailers don't follow that format as specified, so

28586

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

28587

the date, parsedate() returns a 9-tuple that can be passed

28588

directly to time.mktime(); otherwise None will be

28589

returned. Note that fields 6, 7, and 8 of the result tuple are not

28590

usable.</description>

28591

<param name="datedate" optional="0">datedate</param>

28592

<insert>parsedate(datedate)</insert><dialog title="Insert parsedate">parsedate(%0)</dialog><info title="Info window"></info></function>

28593

28594

28595

<description>Performs the same function as parsedate(), but returns

28596

either None or a 10-tuple; the first 9 elements make up a tuple

28597

that can be passed directly to time.mktime(), and the tenth

28598

is the offset of the date's timezone from UTC (which is the official

28599

term for Greenwich Mean Time). (Note that the sign of the timezone

28600

offset is the opposite of the sign of the time.timezone

28601

variable for the same timezone; the latter variable follows the

28602

standard while this module follows 2822.) If the input

28603

string has no timezone, the last element of the tuple returned is

28604

None. Note that fields 6, 7, and 8 of the result tuple are not

28605

usable.</description>

28606

<param name="datedate" optional="0">datedate</param>

28607

<insert>parsedate_tz(datedate)</insert><dialog title="Insert parsedate_tz">parsedate_tz(%0)</dialog><info title="Info window"></info></function>

28608

28609

28610

<description>Turn a 10-tuple as returned by parsedate_tz() into a UTC

28611

timestamp. If the timezone item in the tuple is None, assume

28612

local time. Minor deficiency: this first interprets the first 8

28613

elements as a local time and then compensates for the timezone

28614

difference; this may yield a slight error around daylight savings time

28615

switch dates. Not enough to worry about for common use.</description>

28616

<param name="tupletuple" optional="0">tupletuple</param>

28617

<insert>mktime_tz(tupletuple)</insert><dialog title="Insert mktime_tz">mktime_tz(%0)</dialog><info title="Info window"></info></function>

28618

28619

28620

<description>A Message instance has the following methods:

28621

</description>

28622

28623

<description>Seek to the start of the message body. This only works if the file

28624

object is seekable.</description>

28625

28626

<insert>rewindbody()</insert><dialog title="Insert rewindbody">rewindbody()</dialog><info title="Info window"></info></function>

28627

28628

28629

<description>Returns a line's canonicalized fieldname (the dictionary key that will

28630

be used to index it) if the line is a legal 2822 header; otherwise

28631

returns None (implying that parsing should stop here and the

28632

line be pushed back on the input stream). It is sometimes useful to

28633

override this method in a subclass.</description>

28634

<param name="lineline" optional="0">lineline</param>

28635

<insert>isheader(lineline)</insert><dialog title="Insert isheader">isheader(%0)</dialog><info title="Info window"></info></function>

28636

28637

28638

<description>Return true if the given line is a delimiter on which Message should

28639

stop. The delimiter line is consumed, and the file object's read

28640

location positioned immediately after it. By default this method just

28641

checks that the line is blank, but you can override it in a subclass.</description>

28642

<param name="lineline" optional="0">lineline</param>

28643

<insert>islast(lineline)</insert><dialog title="Insert islast">islast(%0)</dialog><info title="Info window"></info></function>

28644

28645

28646

<description>Return True if the given line should be ignored entirely, just skipped.

28647

By default this is a stub that always returns False, but you can

28648

override it in a subclass.</description>

28649

<param name="lineline" optional="0">lineline</param>

28650

<insert>iscomment(lineline)</insert><dialog title="Insert iscomment">iscomment(%0)</dialog><info title="Info window"></info></function>

28651

28652

28653

<description>Return a list of lines consisting of all headers matching

28654

name, if any. Each physical line, whether it is a continuation

28655

line or not, is a separate list item. Return the empty list if no

28656

header matches name.</description>

28657

<param name="namename" optional="0">namename</param>

28658

<insert>getallmatchingheaders(namename)</insert><dialog title="Insert getallmatchingheaders">getallmatchingheaders(%0)</dialog><info title="Info window"></info></function>

28659

28660

28661

<description>Return a list of lines comprising the first header matching

28662

name, and its continuation line(s), if any. Return

28663

None if there is no header matching name.</description>

28664

<param name="namename" optional="0">namename</param>

28665

<insert>getfirstmatchingheader(namename)</insert><dialog title="Insert getfirstmatchingheader">getfirstmatchingheader(%0)</dialog><info title="Info window"></info></function>

28666

28667

28668

<description>Return a single string consisting of the text after the colon in the

28669

first header matching name. This includes leading whitespace,

28670

the trailing linefeed, and internal linefeeds and whitespace if there

28671

any continuation line(s) were present. Return None if there is

28672

no header matching name.</description>

28673

<param name="namename" optional="0">namename</param>

28674

<insert>getrawheader(namename)</insert><dialog title="Insert getrawheader">getrawheader(%0)</dialog><info title="Info window"></info></function>

28675

28676

28677

<description>Like getrawheader(name), but strip leading and trailing

28678

whitespace. Internal whitespace is not stripped. The optional

28679

default argument can be used to specify a different default to

28680

be returned when there is no header matching name.</description>

28681

<param name="name" optional="0">name</param><param name="default" optional="1">default</param>

28682

<insert>getheader(name, [default])</insert><dialog title="Insert getheader">getheader(%0, %1)</dialog><info title="Info window"></info></function>

28683

28684

28685

<description>An alias for getheader(), to make the interface more compatible with regular dictionaries.</description>

28686

<param name="name" optional="0">name</param><param name="default" optional="1">default</param>

28687

<insert>get(name, [default])</insert><dialog title="Insert get">get(%0, %1)</dialog><info title="Info window"></info></function>

28688

28689

28690

<description>Return a pair (full name, email address) parsed

28691

from the string returned by getheader(name). If no

28692

header matching name exists, return (None, None);

28693

otherwise both the full name and the address are (possibly empty)

28694

strings.

28695

Example: If m's first From header contains the

28696

string 'jack@cwi.nl (Jack Jansen)', then

28697

m.getaddr('From') will yield the pair

28698

('Jack Jansen', 'jack@cwi.nl').

28699

If the header contained

28700

'Jack Jansen <jack@cwi.nl>' instead, it would yield the

28701

exact same result.</description>

28702

<param name="namename" optional="0">namename</param>

28703

<insert>getaddr(namename)</insert><dialog title="Insert getaddr">getaddr(%0)</dialog><info title="Info window"></info></function>

28704

28705

28706

<description>This is similar to getaddr(list), but parses a header

28707

containing a list of email addresses (e.g. To header) and

28708

returns a list of (full name, email address) pairs

28709

(even if there was only one address in the header). If there is no

28710

header matching name, return an empty list.

28711

If multiple headers exist that match the named header (e.g. if there

28712

are several Cc headers), all are parsed for addresses.

28713

Any continuation lines the named headers contain are also parsed.</description>

28714

<param name="namename" optional="0">namename</param>

28715

<insert>getaddrlist(namename)</insert><dialog title="Insert getaddrlist">getaddrlist(%0)</dialog><info title="Info window"></info></function>

28716

28717

28718

<description>Retrieve a header using getheader() and parse it into a 9-tuple

28719

compatible with time.mktime(); note that fields 6, 7, and 8 are not usable. If there is no header matching

28720

name, or it is unparsable, return None.

28721

Date parsing appears to be a black art, and not all mailers adhere to

28722

the standard. While it has been tested and found correct on a large

28723

collection of email from many sources, it is still possible that this

28724

function may occasionally yield an incorrect result.</description>

28725

<param name="namename" optional="0">namename</param>

28726

<insert>getdate(namename)</insert><dialog title="Insert getdate">getdate(%0)</dialog><info title="Info window"></info></function>

28727

28728

28729

<description>Retrieve a header using getheader() and parse it into a

28730

10-tuple; the first 9 elements will make a tuple compatible with

28731

time.mktime(), and the 10th is a number giving the offset

28732

of the date's timezone from UTC. Note that fields 6, 7, and 8 are not usable. Similarly to getdate(), if

28733

there is no header matching name, or it is unparsable, return

28734

None.</description>

28735

<param name="namename" optional="0">namename</param>

28736

<insert>getdate_tz(namename)</insert><dialog title="Insert getdate_tz">getdate_tz(%0)</dialog><info title="Info window"></info></function>

28737

28738

</group>

28739

28740

<description>An AddressList instance has the following methods:

28741

</description>

28742

28743

<description>Return the number of addresses in the address list.</description>

28744

28745

28746

28747

28748

<description>Return a canonicalized string representation of the address list.

28749

Addresses are rendered in "name" <host@domain> form, comma-separated.</description>

28750

28751

28752

28753

28754

<description>Return a new AddressList instance that contains all addresses

28755

in both AddressList operands, with duplicates removed (set

28756

union).</description>

28757

<param name="alistalist" optional="0">alistalist</param>

28758

<insert>__add__(alistalist)</insert><dialog title="Insert __add__">__add__(%0)</dialog><info title="Info window"></info></function>

28759

28760

28761

<description>In-place version of __add__(); turns this AddressList

28762

instance into the union of itself and the right-hand instance,

28763

alist.</description>

28764

<param name="alistalist" optional="0">alistalist</param>

28765

<insert>__iadd__(alistalist)</insert><dialog title="Insert __iadd__">__iadd__(%0)</dialog><info title="Info window"></info></function>

28766

28767

28768

<description>Return a new AddressList instance that contains every address

28769

in the left-hand AddressList operand that is not present in

28770

the right-hand address operand (set difference).</description>

28771

<param name="alistalist" optional="0">alistalist</param>

28772

<insert>__sub__(alistalist)</insert><dialog title="Insert __sub__">__sub__(%0)</dialog><info title="Info window"></info></function>

28773

28774

28775

<description>In-place version of __sub__(), removing addresses in this

28776

list which are also in alist.</description>

28777

<param name="alistalist" optional="0">alistalist</param>

28778

<insert>__isub__(alistalist)</insert><dialog title="Insert __isub__">__isub__(%0)</dialog><info title="Info window"></info></function>

28779

28780

</group>

28781

</group>

28782

28783

<description>Encode and decode files using the MIME base64 data.

28784

</description>

28785

28786

<description>Decode the contents of the input file and write the resulting

28787

binary data to the output file.

28788

input and output must either be file objects or objects that

28789

mimic the file object interface. input will be read until

28790

input.read() returns an empty string.</description>

28791

<param name="input" optional="0">input</param><param name="output output" optional="0">output output</param>

28792

<insert>decode(input, output output)</insert><dialog title="Insert decode">decode(%0, %1)</dialog><info title="Info window"></info></function>

28793

28794

28795

<description>Decode the string s, which must contain one or more lines of

28796

base64 encoded data, and return a string containing the resulting

28797

binary data.</description>

28798

28799

<insert>decodestring(ss)</insert><dialog title="Insert decodestring">decodestring(%0)</dialog><info title="Info window"></info></function>

28800

28801

28802

<description>Encode the contents of the input file and write the resulting

28803

base64 encoded data to the output file.

28804

input and output must either be file objects or objects that

28805

mimic the file object interface. input will be read until

28806

input.read() returns an empty string. encode()

28807

returns the encoded data plus a trailing newline character

28808

('\n').</description>

28809

<param name="input" optional="0">input</param><param name="output output" optional="0">output output</param>

28810

<insert>encode(input, output output)</insert><dialog title="Insert encode">encode(%0, %1)</dialog><info title="Info window"></info></function>

28811

28812

28813

<description>Encode the string s, which can contain arbitrary binary data,

28814

and return a string containing one or more lines of

28815

base64-encoded data. encodestring() returns a

28816

string containing one or more lines of base64-encoded data

28817

always including an extra trailing newline ('\n').</description>

28818

28819

<insert>encodestring(ss)</insert><dialog title="Insert encodestring">encodestring(%0)</dialog><info title="Info window"></info></function>

28820

28821

</group>

28822

28823

<description>Tools for converting between binary and various

28824

-encoded binary representations.

28825

The binascii module contains a number of methods to convert

28826

between binary and various -encoded binary

28827

representations. Normally, you will not use these functions directly

28828

but use wrapper modules like uuuu or

28829

binhexbinhex instead, this module solely

28830

exists because bit-manipulation of large amounts of data is slow in

28831

Python.

28832

The binascii module defines the following functions:

28833

</description>

28834

28835

<description>Convert a single line of uuencoded data back to binary and return the

28836

binary data. Lines normally contain 45 (binary) bytes, except for the

28837

last line. Line data may be followed by whitespace.</description>

28838

<param name="stringstring" optional="0">stringstring</param>

28839

<insert>a2b_uu(stringstring)</insert><dialog title="Insert a2b_uu">a2b_uu(%0)</dialog><info title="Info window"></info></function>

28840

28841

28842

<description>Convert binary data to a line of ASCII characters, the return value

28843

is the converted line, including a newline char. The length of

28844

data should be at most 45.</description>

28845

<param name="datadata" optional="0">datadata</param>

28846

<insert>b2a_uu(datadata)</insert><dialog title="Insert b2a_uu">b2a_uu(%0)</dialog><info title="Info window"></info></function>

28847

28848

28849

<description>Convert a block of base64 data back to binary and return the

28850

binary data. More than one line may be passed at a time.</description>

28851

<param name="stringstring" optional="0">stringstring</param>

28852

<insert>a2b_base64(stringstring)</insert><dialog title="Insert a2b_base64">a2b_base64(%0)</dialog><info title="Info window"></info></function>

28853

28854

28855

<description>Convert binary data to a line of ASCII characters in base64 coding.

28856

The return value is the converted line, including a newline char.

28857

The length of data should be at most 57 to adhere to the base64

28858

standard.</description>

28859

<param name="datadata" optional="0">datadata</param>

28860

<insert>b2a_base64(datadata)</insert><dialog title="Insert b2a_base64">b2a_base64(%0)</dialog><info title="Info window"></info></function>

28861

28862

28863

<description>Convert a block of quoted-printable data back to binary and return the

28864

binary data. More than one line may be passed at a time.

28865

If the optional argument header is present and true, underscores

28866

will be decoded as spaces.</description>

28867

<param name="string" optional="0">string</param><param name="header" optional="1">header</param>

28868

<insert>a2b_qp(string, [header])</insert><dialog title="Insert a2b_qp">a2b_qp(%0, %1)</dialog><info title="Info window"></info></function>

28869

28870

28871

<description>Convert binary data to a line(s) of ASCII characters in

28872

quoted-printable encoding. The return value is the converted line(s).

28873

If the optional argument quotetabs is present and true, all tabs

28874

and spaces will be encoded. If the optional argument header is

28875

present and true, spaces will be encoded as underscores per RFC1522.

28876

If the optional argument header is present and false, newline

28877

characters will be encoded as well, otherwise linefeed conversion might

28878

corrupt the binary data stream.</description>

28879

<param name="data" optional="0">data</param><param name="quotetabs" optional="1">quotetabs</param><param name="istext" optional="1">istext</param><param name="header" optional="1">header</param>

28880

<insert>b2a_qp(data, [quotetabs], [istext], [header])</insert><dialog title="Insert b2a_qp">b2a_qp(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

28881

28882

28883

<description>Convert binhex4 formatted ASCII data to binary, without doing

28884

RLE-decompression. The string should contain a complete number of

28885

binary bytes, or (in case of the last portion of the binhex4 data)

28886

have the remaining bits zero.</description>

28887

<param name="stringstring" optional="0">stringstring</param>

28888

<insert>a2b_hqx(stringstring)</insert><dialog title="Insert a2b_hqx">a2b_hqx(%0)</dialog><info title="Info window"></info></function>

28889

28890

28891

<description>Perform RLE-decompression on the data, as per the binhex4

28892

standard. The algorithm uses 0x90 after a byte as a repeat

28893

indicator, followed by a count. A count of 0 specifies a byte

28894

value of 0x90. The routine returns the decompressed data,

28895

unless data input data ends in an orphaned repeat indicator, in which

28896

case the Incomplete exception is raised.</description>

28897

<param name="datadata" optional="0">datadata</param>

28898

<insert>rledecode_hqx(datadata)</insert><dialog title="Insert rledecode_hqx">rledecode_hqx(%0)</dialog><info title="Info window"></info></function>

28899

28900

28901

<description>Perform binhex4 style RLE-compression on data and return the

28902

result.</description>

28903

<param name="datadata" optional="0">datadata</param>

28904

<insert>rlecode_hqx(datadata)</insert><dialog title="Insert rlecode_hqx">rlecode_hqx(%0)</dialog><info title="Info window"></info></function>

28905

28906

28907

<description>Perform hexbin4 binary-to-ASCII translation and return the

28908

resulting string. The argument should already be RLE-coded, and have a

28909

length divisible by 3 (except possibly the last fragment).</description>

28910

<param name="datadata" optional="0">datadata</param>

28911

<insert>b2a_hqx(datadata)</insert><dialog title="Insert b2a_hqx">b2a_hqx(%0)</dialog><info title="Info window"></info></function>

28912

28913

28914

<description>Compute the binhex4 crc value of data, starting with an initial

28915

crc and returning the result.</description>

28916

28917

28918

28919

28920

<description>Compute CRC-32, the 32-bit checksum of data, starting with an initial

28921

crc. This is consistent with the ZIP file checksum. Since the

28922

algorithm is designed for use as a checksum algorithm, it is not

28923

suitable for use as a general hash algorithm. Use as follows:

28924

print binascii.crc32("hello world")

28925

# Or, in two pieces:

28926

crc = binascii.crc32("hello")

28927

crc = binascii.crc32(" world", crc)

28928

print crc

28929

</description>

28930

28931

28932

28933

28934

<description>hexlify{data}

28935

Return the hexadecimal representation of the binary data. Every

28936

byte of data is converted into the corresponding 2-digit hex

28937

representation. The resulting string is therefore twice as long as

28938

the length of data.</description>

28939

<param name="datadata" optional="0">datadata</param>

28940

<insert>b2a_hex(datadata)</insert><dialog title="Insert b2a_hex">b2a_hex(%0)</dialog><info title="Info window"></info></function>

28941

28942

28943

<description>unhexlify{hexstr}

28944

Return the binary data represented by the hexadecimal string

28945

hexstr. This function is the inverse of b2a_hex().

28946

hexstr must contain an even number of hexadecimal digits (which

28947

can be upper or lower case), otherwise a TypeError is

28948

raised.</description>

28949

<param name="hexstrhexstr" optional="0">hexstrhexstr</param>

28950

<insert>a2b_hex(hexstrhexstr)</insert><dialog title="Insert a2b_hex">a2b_hex(%0)</dialog><info title="Info window"></info></function>

28951

28952

</group>

28953

28954

<description>Encode and decode files in binhex4 format.

28955

This module encodes and decodes files in binhex4 format, a format

28956

allowing representation of Macintosh files in . On the Macintosh,

28957

both forks of a file and the finder information are encoded (or

28958

decoded), on other platforms only the data fork is handled.

28959

The binhex module defines the following functions:

28960

</description>

28961

28962

<description>Convert a binary file with filename input to binhex file

28963

output. The output parameter can either be a filename or a

28964

file-like object (any object supporting a write() and

28965

close() method).</description>

28966

<param name="input" optional="0">input</param><param name="output output" optional="0">output output</param>

28967

<insert>binhex(input, output output)</insert><dialog title="Insert binhex">binhex(%0, %1)</dialog><info title="Info window"></info></function>

28968

28969

28970

<description>Decode a binhex file input. input may be a filename or a

28971

file-like object supporting read() and close() methods.

28972

The resulting file is written to a file named output, unless the

28973

argument is omitted in which case the output filename is read from the

28974

binhex file.</description>

28975

<param name="input" optional="0">input</param><param name="output" optional="1">output</param>

28976

<insert>hexbin(input, [output])</insert><dialog title="Insert hexbin">hexbin(%0, %1)</dialog><info title="Info window"></info></function>

28977

28978

28979

</group>

28980

</group>

28981

28982

<description>Encode and decode files using the MIME

28983

quoted-printable encoding.

28984

This module performs quoted-printable transport encoding and decoding,

28985

as defined in 1521: ``MIME (Multipurpose Internet Mail

28986

Extensions) Part One: Mechanisms for Specifying and Describing the

28987

Format of Internet Message Bodies''. The quoted-printable encoding is

28988

designed for data where there are relatively few nonprintable

28989

characters; the base64 encoding scheme available via the

28990

base64 module is more compact if there are many such

28991

characters, as when sending a graphics file.

28992

</description>

28993

28994

<description>Decode the contents of the input file and write the resulting

28995

decoded binary data to the output file.

28996

input and output must either be file objects or objects that

28997

mimic the file object interface. input will be read until

28998

input.readline() returns an empty string.

28999

If the optional argument header is present and true, underscore

29000

will be decoded as space. This is used to decode

29001

``Q''-encoded headers as described in 1522: ``MIME (Multipurpose Internet Mail Extensions)

29002

Part Two: Message Header Extensions for Non-ASCII Text''.</description>

29003

<param name="input" optional="0">input</param><param name="output" optional="0">output</param><param name="header" optional="1">header</param>

29004

<insert>decode(input, output, [header])</insert><dialog title="Insert decode">decode(%0, %1, %2)</dialog><info title="Info window"></info></function>

29005

29006

29007

<description>Encode the contents of the input file and write the resulting

29008

quoted-printable data to the output file.

29009

input and output must either be file objects or objects that

29010

mimic the file object interface. input will be read until

29011

input.readline() returns an empty string.

29012

quotetabs is a flag which controls whether to encode embedded

29013

spaces and tabs; when true it encodes such embedded whitespace, and

29014

when false it leaves them unencoded. Note that spaces and tabs

29015

appearing at the end of lines are always encoded, as per 1521.</description>

29016

<param name="input" optional="0">input</param><param name="output" optional="0">output</param><param name="quotetabs quotetabs" optional="0">quotetabs quotetabs</param>

29017

<insert>encode(input, output, quotetabs quotetabs)</insert><dialog title="Insert encode">encode(%0, %1, %2)</dialog><info title="Info window"></info></function>

29018

29019

29020

<description>Like decode(), except that it accepts a source string and

29021

returns the corresponding decoded string.</description>

29022

<param name="s" optional="0">s</param><param name="header" optional="1">header</param>

29023

<insert>decodestring(s, [header])</insert><dialog title="Insert decodestring">decodestring(%0, %1)</dialog><info title="Info window"></info></function>

29024

29025

29026

<description>Like encode(), except that it accepts a source string and

29027

returns the corresponding encoded string. quotetabs is optional

29028

(defaulting to 0), and is passed straight through to

29029

encode().</description>

29030

<param name="s" optional="0">s</param><param name="quotetabs" optional="1">quotetabs</param>

29031

<insert>encodestring(s, [quotetabs])</insert><dialog title="Insert encodestring">encodestring(%0, %1)</dialog><info title="Info window"></info></function>

29032

29033

</group>

29034

29035

<description>Encode and decode files in uuencode format.

29036

This module encodes and decodes files in uuencode format, allowing

29037

arbitrary binary data to be transferred over ASCII-only connections.

29038

Wherever a file argument is expected, the methods accept a file-like

29039

object. For backwards compatibility, a string containing a pathname

29040

is also accepted, and the corresponding file will be opened for

29041

reading and writing; the pathname '-' is understood to mean the

29042

standard input or output. However, this interface is deprecated; it's

29043

better for the caller to open the file itself, and be sure that, when

29044

required, the mode is 'rb' or 'wb' on Windows.

29045

This code was contributed by Lance Ellinghouse, and modified by Jack

29046

Jansen.

29047

</description>

29048

29049

<description>Uuencode file in_file into file out_file. The uuencoded

29050

file will have the header specifying name and mode as

29051

the defaults for the results of decoding the file. The default

29052

defaults are taken from in_file, or '-' and 0666

29053

respectively.</description>

29054

29055

<insert>encode(in_file, out_file, [name], [mode])</insert><dialog title="Insert encode">encode(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

29056

29057

29058

<description>This call decodes uuencoded file in_file placing the result on

29059

file out_file. If out_file is a pathname, mode is

29060

used to set the permission bits if the file must be

29061

created. Defaults for out_file and mode are taken from

29062

the uuencode header. However, if the file specified in the header

29063

already exists, a uu.Error is raised.</description>

29064

29065

<insert>decode(in_file, [out_file], [mode])</insert><dialog title="Insert decode">decode(%0, %1, %2)</dialog><info title="Info window"></info></function>

29066

29067

</group>

29068

29069

<description>Encoders and decoders for the External Data

29070

Representation (XDR).

29071

</description>

29072

29073

<description>Packer is the class for packing data into XDR representation.

29074

The Packer class is instantiated with no arguments.</description>

29075

29076

<insert>Packer()</insert><dialog title="Insert Packer">Packer()</dialog><info title="Info window"></info></function>

29077

29078

29079

<description>Unpacker is the complementary class which unpacks XDR data

29080

values from a string buffer. The input buffer is given as

29081

data.</description>

29082

<param name="datadata" optional="0">datadata</param>

29083

<insert>Unpacker(datadata)</insert><dialog title="Insert Unpacker">Unpacker(%0)</dialog><info title="Info window"></info></function>

29084

29085

29086

<description>Packer instances have the following methods:

29087

</description>

29088

29089

<description>Returns the current pack buffer as a string.</description>

29090

29091

<insert>get_buffer()</insert><dialog title="Insert get_buffer">get_buffer()</dialog><info title="Info window"></info></function>

29092

29093

29094

<description>Resets the pack buffer to the empty string.</description>

29095

29096

<insert>reset()</insert><dialog title="Insert reset">reset()</dialog><info title="Info window"></info></function>

29097

29098

29099

<description>Packs the single-precision floating point number value.</description>

29100

<param name="valuevalue" optional="0">valuevalue</param>

29101

<insert>pack_float(valuevalue)</insert><dialog title="Insert pack_float">pack_float(%0)</dialog><info title="Info window"></info></function>

29102

29103

29104

<description>Packs the double-precision floating point number value.</description>

29105

<param name="valuevalue" optional="0">valuevalue</param>

29106

<insert>pack_double(valuevalue)</insert><dialog title="Insert pack_double">pack_double(%0)</dialog><info title="Info window"></info></function>

29107

29108

29109

<description>Packs a fixed length string, s. n is the length of the

29110

string but it is not packed into the data buffer. The string

29111

is padded with null bytes if necessary to guaranteed 4 byte alignment.</description>

29112

29113

<insert>pack_fstring(n, s s)</insert><dialog title="Insert pack_fstring">pack_fstring(%0, %1)</dialog><info title="Info window"></info></function>

29114

29115

29116

<description>Packs a fixed length opaque data stream, similarly to

29117

pack_fstring().</description>

29118

29119

<insert>pack_fopaque(n, data data)</insert><dialog title="Insert pack_fopaque">pack_fopaque(%0, %1)</dialog><info title="Info window"></info></function>

29120

29121

29122

<description>Packs a variable length string, s. The length of the string is

29123

first packed as an unsigned integer, then the string data is packed

29124

with pack_fstring().</description>

29125

29126

<insert>pack_string(ss)</insert><dialog title="Insert pack_string">pack_string(%0)</dialog><info title="Info window"></info></function>

29127

29128

29129

<description>Packs a variable length opaque data string, similarly to

29130

pack_string().</description>

29131

<param name="datadata" optional="0">datadata</param>

29132

<insert>pack_opaque(datadata)</insert><dialog title="Insert pack_opaque">pack_opaque(%0)</dialog><info title="Info window"></info></function>

29133

29134

29135

<description>Packs a variable length byte stream, similarly to pack_string().</description>

29136

<param name="bytesbytes" optional="0">bytesbytes</param>

29137

<insert>pack_bytes(bytesbytes)</insert><dialog title="Insert pack_bytes">pack_bytes(%0)</dialog><info title="Info window"></info></function>

29138

29139

29140

<description>Packs a list of homogeneous items. This method is useful for

29141

lists with an indeterminate size; i.e. the size is not available until

29142

the entire list has been walked. For each item in the list, an

29143

unsigned integer 1 is packed first, followed by the data value

29144

from the list. pack_item is the function that is called to pack

29145

the individual item. At the end of the list, an unsigned integer

29146

0 is packed.

29147

For example, to pack a list of integers, the code might appear like

29148

this:

29149

import xdrlib

29150

p = xdrlib.Packer()

29151

p.pack_list([1, 2, 3], p.pack_int)

29152

</description>

29153

29154

29155

29156

29157

<description>Packs a fixed length list (array) of homogeneous items. n

29158

is the length of the list; it is not packed into the buffer,

29159

but a ValueError exception is raised if

29160

len(array) is not equal to n. As above,

29161

pack_item is the function used to pack each element.</description>

29162

<param name="n" optional="0">n</param><param name="array" optional="0">array</param><param name="pack_item pack_item" optional="0">pack_item pack_item</param>

29163

<insert>pack_farray(n, array, pack_item pack_item)</insert><dialog title="Insert pack_farray">pack_farray(%0, %1, %2)</dialog><info title="Info window"></info></function>

29164

29165

29166

<description>Packs a variable length list of homogeneous items. First, the

29167

length of the list is packed as an unsigned integer, then each element

29168

is packed as in pack_farray() above.</description>

29169

29170

<insert>pack_array(list, pack_item pack_item)</insert><dialog title="Insert pack_array">pack_array(%0, %1)</dialog><info title="Info window"></info></function>

29171

29172

</group>

29173

29174

<description>The Unpacker class offers the following methods:

29175

</description>

29176

29177

<description>Resets the string buffer with the given data.</description>

29178

<param name="datadata" optional="0">datadata</param>

29179

<insert>reset(datadata)</insert><dialog title="Insert reset">reset(%0)</dialog><info title="Info window"></info></function>

29180

29181

29182

<description>Returns the current unpack position in the data buffer.</description>

29183

29184

<insert>get_position()</insert><dialog title="Insert get_position">get_position()</dialog><info title="Info window"></info></function>

29185

29186

29187

<description>Sets the data buffer unpack position to position. You should be

29188

careful about using get_position() and set_position().</description>

29189

<param name="positionposition" optional="0">positionposition</param>

29190

<insert>set_position(positionposition)</insert><dialog title="Insert set_position">set_position(%0)</dialog><info title="Info window"></info></function>

29191

29192

29193

<description>Returns the current unpack data buffer as a string.</description>

29194

29195

<insert>get_buffer()</insert><dialog title="Insert get_buffer">get_buffer()</dialog><info title="Info window"></info></function>

29196

29197

29198

<description>Indicates unpack completion. Raises an Error exception

29199

if all of the data has not been unpacked.</description>

29200

29201

29202

29203

29204

<description>Unpacks a single-precision floating point number.</description>

29205

29206

<insert>unpack_float()</insert><dialog title="Insert unpack_float">unpack_float()</dialog><info title="Info window"></info></function>

29207

29208

29209

<description>Unpacks a double-precision floating point number, similarly to

29210

unpack_float().</description>

29211

29212

<insert>unpack_double()</insert><dialog title="Insert unpack_double">unpack_double()</dialog><info title="Info window"></info></function>

29213

29214

29215

<description>Unpacks and returns a fixed length string. n is the number of

29216

characters expected. Padding with null bytes to guaranteed 4 byte

29217

alignment is assumed.</description>

29218

29219

<insert>unpack_fstring(nn)</insert><dialog title="Insert unpack_fstring">unpack_fstring(%0)</dialog><info title="Info window"></info></function>

29220

29221

29222

<description>Unpacks and returns a fixed length opaque data stream, similarly to

29223

unpack_fstring().</description>

29224

29225

<insert>unpack_fopaque(nn)</insert><dialog title="Insert unpack_fopaque">unpack_fopaque(%0)</dialog><info title="Info window"></info></function>

29226

29227

29228

<description>Unpacks and returns a variable length string. The length of the

29229

string is first unpacked as an unsigned integer, then the string data

29230

is unpacked with unpack_fstring().</description>

29231

29232

<insert>unpack_string()</insert><dialog title="Insert unpack_string">unpack_string()</dialog><info title="Info window"></info></function>

29233

29234

29235

<description>Unpacks and returns a variable length opaque data string, similarly to

29236

unpack_string().</description>

29237

29238

<insert>unpack_opaque()</insert><dialog title="Insert unpack_opaque">unpack_opaque()</dialog><info title="Info window"></info></function>

29239

29240

29241

<description>Unpacks and returns a variable length byte stream, similarly to

29242

unpack_string().</description>

29243

29244

<insert>unpack_bytes()</insert><dialog title="Insert unpack_bytes">unpack_bytes()</dialog><info title="Info window"></info></function>

29245

29246

29247

<description>Unpacks and returns a list of homogeneous items. The list is unpacked

29248

one element at a time

29249

by first unpacking an unsigned integer flag. If the flag is 1,

29250

then the item is unpacked and appended to the list. A flag of

29251

0 indicates the end of the list. unpack_item is the

29252

function that is called to unpack the items.</description>

29253

<param name="unpack_itemunpack_item" optional="0">unpack_itemunpack_item</param>

29254

<insert>unpack_list(unpack_itemunpack_item)</insert><dialog title="Insert unpack_list">unpack_list(%0)</dialog><info title="Info window"></info></function>

29255

29256

29257

<description>Unpacks and returns (as a list) a fixed length array of homogeneous

29258

items. n is number of list elements to expect in the buffer.

29259

As above, unpack_item is the function used to unpack each element.</description>

29260

<param name="n" optional="0">n</param><param name="unpack_item unpack_item" optional="0">unpack_item unpack_item</param>

29261

<insert>unpack_farray(n, unpack_item unpack_item)</insert><dialog title="Insert unpack_farray">unpack_farray(%0, %1)</dialog><info title="Info window"></info></function>

29262

29263

29264

<description>Unpacks and returns a variable length list of homogeneous items.

29265

First, the length of the list is unpacked as an unsigned integer, then

29266

each element is unpacked as in unpack_farray() above.</description>

29267

<param name="unpack_itemunpack_item" optional="0">unpack_itemunpack_item</param>

29268

<insert>unpack_array(unpack_itemunpack_item)</insert><dialog title="Insert unpack_array">unpack_array(%0)</dialog><info title="Info window"></info></function>

29269

29270

</group>

29271

29272

</group>

29273

</group>

29274

29275

<description>% Note the needed for ... ;-(

29276

Loading of .netrc files.

29277

New in version 1.5.2

29278

The netrc class parses and encapsulates the netrc file format

29279

used by the ftp program and other FTP clients.

29280

</description>

29281

29282

<description>A netrc instance or subclass instance encapsulates data from a netrc file. The initialization argument, if present, specifies the

29283

file to parse. If no argument is given, the file .netrc in the

29284

user's home directory will be read. Parse errors will raise

29285

NetrcParseError with diagnostic information including the

29286

file name, line number, and terminating token.</description>

29287

29288

<insert>netrc(file)</insert><dialog title="Insert netrc">netrc(%0)</dialog><info title="Info window"></info></function>

29289

29290

29291

<description>A netrc instance has the following methods:

29292

</description>

29293

29294

<description>Return a 3-tuple (login, account, password)

29295

of authenticators for host. If the netrc file did not

29296

contain an entry for the given host, return the tuple associated with

29297

the `default' entry. If neither matching host nor default entry is

29298

available, return None.</description>

29299

<param name="hosthost" optional="0">hosthost</param>

29300

<insert>authenticators(hosthost)</insert><dialog title="Insert authenticators">authenticators(%0)</dialog><info title="Info window"></info></function>

29301

29302

29303

<description>Dump the class data as a string in the format of a netrc file.

29304

(This discards comments and may reorder the entries.)</description>

29305

29306

29307

29308

</group>

29309

</group>

29310

29311

<description>Loads a robots.txt file and

29312

answers questions about fetchability of other URLs.

29313

</description>

29314

29315

<description>This class provides a set of methods to read, parse and answer questions

29316

about a single robots.txt file.

29317

{set_url}{url}

29318

Sets the URL referring to a robots.txt file.</description>

29319

29320

<insert>RobotFileParser()</insert><dialog title="Insert RobotFileParser">RobotFileParser()</dialog><info title="Info window"></info></function>

29321

29322

29323

<description>Reads the robots.txt URL and feeds it to the parser.</description>

29324

29325

29326

29327

29328

<description>Parses the lines argument.</description>

29329

<param name="lineslines" optional="0">lineslines</param>

29330

<insert>parse(lineslines)</insert><dialog title="Insert parse">parse(%0)</dialog><info title="Info window"></info></function>

29331

29332

29333

<description>Returns True if the useragent is allowed to fetch the url

29334

according to the rules contained in the parsed robots.txt file.</description>

29335

<param name="useragent" optional="0">useragent</param><param name="url url" optional="0">url url</param>

29336

<insert>can_fetch(useragent, url url)</insert><dialog title="Insert can_fetch">can_fetch(%0, %1)</dialog><info title="Info window"></info></function>

29337

29338

29339

<description>Returns the time the robots.txt file was last fetched. This is

29340

useful for long-running web spiders that need to check for new

29341

robots.txt files periodically.</description>

29342

29343

<insert>mtime()</insert><dialog title="Insert mtime">mtime()</dialog><info title="Info window"></info></function>

29344

29345

29346

<description>Sets the time the robots.txt file was last fetched to the current

29347

time.</description>

29348

29349

<insert>modified()</insert><dialog title="Insert modified">modified()</dialog><info title="Info window"></info></function>

29350

29351

</group>

29352

29353

<description>Write and read tabular data to and from delimited files.

29354

New in version 2.3

29355

</description>

29356

29357

<description>The csv module defines the following functions:

29358

</description>

29359

29360

<description>Return a reader object which will iterate over lines in the given

29361

{}csvfile. csvfile can be any object which supports the

29362

iterator protocol and returns a string each time its next

29363

method is called. If csvfile is a file object, it must be opened with

29364

the 'b' flag on platforms where that makes a difference. An optional

29365

{}dialect parameter can be given

29366

which is used to define a set of parameters specific to a particular CSV

29367

dialect. It may be an instance of a subclass of the Dialect

29368

class or one of the strings returned by the list_dialects

29369

function. The other optional {}fmtparam keyword arguments can be

29370

given to override individual formatting parameters in the current

29371

dialect. For more information about the dialect and formatting

29372

parameters, see section~csv-fmt-params, ``Dialects and Formatting

29373

Parameters'' for details of these parameters.

29374

All data read are returned as strings. No automatic data type

29375

conversion is performed.</description>

29376

<param name="csvfile" optional="0">csvfile</param><param name="dialect" optional="1" default="'excel'">dialect</param><param name="fmtparam" optional="1">fmtparam</param>

29377

<insert>reader(csvfile, [dialect='excel'], [fmtparam])</insert><dialog title="Insert reader">reader(%0, %1, %2)</dialog><info title="Info window"></info></function>

29378

29379

29380

<description>Return a writer object responsible for converting the user's data into

29381

delimited strings on the given file-like object. csvfile can be any

29382

object with a write method. If csvfile is a file object,

29383

it must be opened with the 'b' flag on platforms where that makes a

29384

difference. An optional

29385

{}dialect parameter can be given which is used to define a set of

29386

parameters specific to a particular CSV dialect. It may be an instance

29387

of a subclass of the Dialect class or one of the strings

29388

returned by the list_dialects function. The other optional

29389

{}fmtparam keyword arguments can be given to override individual

29390

formatting parameters in the current dialect. For more information

29391

about the dialect and formatting parameters, see

29392

section~csv-fmt-params, ``Dialects and Formatting Parameters'' for

29393

details of these parameters. To make it as easy as possible to

29394

interface with modules which implement the DB API, the value

29395

None is written as the empty string. While this isn't a

29396

reversible transformation, it makes it easier to dump SQL NULL data values

29397

to CSV files without preprocessing the data returned from a

29398

cursor.fetch*() call. All other non-string data are stringified

29399

with str() before being written.</description>

29400

<param name="csvfile" optional="0">csvfile</param><param name="dialect" optional="1" default="'excel'">dialect</param><param name="fmtparam" optional="1">fmtparam</param>

29401

<insert>writer(csvfile, [dialect='excel'], [fmtparam])</insert><dialog title="Insert writer">writer(%0, %1, %2)</dialog><info title="Info window"></info></function>

29402

29403

29404

<description>Associate dialect with name. dialect must be a subclass

29405

of csv.Dialect. name must be a string or Unicode object.</description>

29406

<param name="name" optional="0">name</param><param name="dialect dialect" optional="0">dialect dialect</param>

29407

<insert>register_dialect(name, dialect dialect)</insert><dialog title="Insert register_dialect">register_dialect(%0, %1)</dialog><info title="Info window"></info></function>

29408

29409

29410

<description>Delete the dialect associated with name from the dialect registry. An

29411

Error is raised if name is not a registered dialect

29412

name.</description>

29413

<param name="namename" optional="0">namename</param>

29414

<insert>unregister_dialect(namename)</insert><dialog title="Insert unregister_dialect">unregister_dialect(%0)</dialog><info title="Info window"></info></function>

29415

29416

29417

<description>Return the dialect associated with name. An Error is

29418

raised if name is not a registered dialect name.</description>

29419

<param name="namename" optional="0">namename</param>

29420

<insert>get_dialect(namename)</insert><dialog title="Insert get_dialect">get_dialect(%0)</dialog><info title="Info window"></info></function>

29421

29422

29423

<description>Return the names of all registered dialects.</description>

29424

29425

<insert>list_dialects()</insert><dialog title="Insert list_dialects">list_dialects()</dialog><info title="Info window"></info></function>

29426

29427

29428

<description>Create an object which operates like a regular reader but maps the

29429

information read into a dict whose keys are given by the optional

29430

{} fieldnames

29431

parameter. If the fieldnames parameter is omitted, the values in

29432

the first row of the csvfile will be used as the fieldnames.

29433

If the row read has fewer fields than the fieldnames sequence,

29434

the value of restval will be used as the default value. If the row

29435

read has more fields than the fieldnames sequence, the remaining data is

29436

added as a sequence keyed by the value of restkey. If the row read

29437

has fewer fields than the fieldnames sequence, the remaining keys take the

29438

value of the optional restval parameter. All other parameters are

29439

interpreted as for reader objects.</description>

29440

<param name="csvfile" optional="0">csvfile</param><param name="fieldnames" optional="1" default="None">fieldnames</param><param name="restkey" optional="1" default="None">restkey</param><param name="restval" optional="1" default="None">restval</param><param name="dialect" optional="1" default="'excel'">dialect</param><param name="fmtparam" optional="1">fmtparam</param>

29441

<insert>DictReader(csvfile, [fieldnames=None], [restkey=None], [restval=None], [dialect='excel'], [fmtparam])</insert><dialog title="Insert DictReader">DictReader(%0, %1, %2, %3, %4, %5)</dialog><info title="Info window"></info></function>

29442

29443

29444

<description>Create an object which operates like a regular writer but maps dictionaries

29445

onto output rows. The fieldnames parameter identifies the order in

29446

which values in the dictionary passed to the writerow() method are

29447

written to the csvfile. The optional restval parameter

29448

specifies the value to be written if the dictionary is missing a key in

29449

fieldnames. If the dictionary passed to the writerow()

29450

method contains a key not found in fieldnames, the optional

29451

extrasaction parameter indicates what action to take. If it is set

29452

to 'raise' a ValueError is raised. If it is set to

29453

'ignore', extra values in the dictionary are ignored. All other

29454

parameters are interpreted as for writer objects.

29455

Note that unlike the DictReader class, the fieldnames

29456

parameter of the DictWriter is not optional. Since Python's

29457

dict objects are not ordered, there is not enough information

29458

available to deduce the order in which the row should be written to the

29459

csvfile.</description>

29460

<param name="csvfile" optional="0">csvfile</param><param name="fieldnames" optional="0">fieldnames</param><param name="restval" optional="1" default="""">restval</param><param name="extrasaction" optional="1" default="'raise'">extrasaction</param><param name="dialect" optional="1" default="'excel'">dialect</param><param name="fmtparam" optional="1">fmtparam</param>

29461

<insert>DictWriter(csvfile, fieldnames, [restval=""], [extrasaction='raise'], [dialect='excel'], [fmtparam])</insert><dialog title="Insert DictWriter">DictWriter(%0, %1, %2, %3, %4, %5)</dialog><info title="Info window"></info></function>

29462

29463

29464

<description>The Sniffer class is used to deduce the format of a CSV file.</description>

29465

29466

<insert>Sniffer()</insert><dialog title="Insert Sniffer">Sniffer()</dialog><info title="Info window"></info></function>

29467

29468

29469

<description>Analyze the given sample and return a Dialect subclass

29470

reflecting the parameters found. If the optional delimiters parameter

29471

is given, it is interpreted as a string containing possible valid delimiter

29472

characters.</description>

29473

<param name="sample" optional="0">sample</param><param name="delimiters" optional="1" default="None">delimiters</param>

29474

<insert>sniff(sample, [delimiters=None])</insert><dialog title="Insert sniff">sniff(%0, %1)</dialog><info title="Info window"></info></function>

29475

29476

29477

<description>Analyze the sample text (presumed to be in CSV format) and return

29478

True if the first row appears to be a series of column

29479

headers.</description>

29480

<param name="samplesample" optional="0">samplesample</param>

29481

<insert>has_header(samplesample)</insert><dialog title="Insert has_header">has_header(%0)</dialog><info title="Info window"></info></function>

29482

29483

</group>

29484

29485

<description>To make it easier to specify the format of input and output records,

29486

specific formatting parameters are grouped together into dialects. A

29487

dialect is a subclass of the Dialect class having a set of specific

29488

methods and a single validate() method. When creating reader

29489

or writer objects, the programmer can specify a string or a subclass

29490

of the Dialect class as the dialect parameter. In addition to, or

29491

instead of, the dialect parameter, the programmer can also specify

29492

individual formatting parameters, which have the same names as the

29493

attributes defined below for the Dialect class.

29494

Dialects support the following attributes:

29495

[Dialect]{delimiter}

29496

A one-character string used to separate fields. It defaults to ','.

29497

[Dialect]{doublequote}

29498

Controls how instances of quotechar appearing inside a field should be

29499

themselves be quoted. When True, the character is doubledd.

29500

When False, the escapechar must be a one-character string

29501

which is used as a prefix to the quotechar. It defaults to

29502

True.

29503

[Dialect]{escapechar}

29504

A one-character string used to escape the delimiter if quoting

29505

is set to QUOTE_NONE. It defaults to None.

29506

[Dialect]{lineterminator}

29507

The string used to terminate lines in the CSV file. It defaults to

29508

'\r\n'.

29509

[Dialect]{quotechar}

29510

A one-character string used to quote elements containing the delimiter

29511

or which start with the quotechar. It defaults to '"'.

29512

[Dialect]{quoting}

29513

Controls when quotes should be generated by the writer. It can take on any

29514

of the QUOTE_* constants (see section~csv-contents)

29515

and defaults to QUOTE_MINIMAL. [Dialect]{skipinitialspace}

29516

When True, whitespace immediately following the delimiter

29517

is ignored. The default is False.

29518

</description>

29519

</group>

29520

29521

<description>Reader objects (DictReader instances and objects returned by

29522

the reader() function) have the following public methods:

29523

[csv reader]{next}{}

29524

Return the next row of the reader's iterable object as a list, parsed

29525

according to the current dialect.

29526

</description>

29527

</group>

29528

29529

<description>Writer objects (DictWriter instances and objects returned by

29530

the writer() function) have the following public methods:

29531

[csv writer]{writerow}{row}

29532

Write the row parameter to the writer's file object, formatted

29533

according to the current dialect.

29534

[csv writer]{writerows}{rows}

29535

Write all the rows parameters to the writer's file object, formatted

29536

according to the current dialect.

29537

</description>

29538

</group>

29539

29540

</group>

29541

</group>

29542

</group>

29543

29544

29545

<description>A simple parser that can handle HTML and XHTML.

29546

This module defines a class HTMLParser which serves as the

29547

basis for parsing text files formatted in HTML</description>

29548

29549

<description>The HTMLParser class is instantiated without arguments.

29550

An HTMLParser instance is fed HTML data and calls handler functions

29551

when tags begin and end. The HTMLParser class is meant to be

29552

overridden by the user to provide a desired behavior.

29553

Unlike the parser in htmllib, this parser does not check

29554

that end tags match start tags or call the end-tag handler for

29555

elements which are closed implicitly by closing an outer element.</description>

29556

29557

<insert>HTMLParser()</insert><dialog title="Insert HTMLParser">HTMLParser()</dialog><info title="Info window"></info></function>

29558

29559

29560

<description>Reset the instance. Loses all unprocessed data. This is called

29561

implicitly at instantiation time.</description>

29562

29563

<insert>reset()</insert><dialog title="Insert reset">reset()</dialog><info title="Info window"></info></function>

29564

29565

29566

<description>Feed some text to the parser. It is processed insofar as it consists

29567

of complete elements; incomplete data is buffered until more data is

29568

fed or close() is called.</description>

29569

<param name="datadata" optional="0">datadata</param>

29570

<insert>feed(datadata)</insert><dialog title="Insert feed">feed(%0)</dialog><info title="Info window"></info></function>

29571

29572

29573

<description>Force processing of all buffered data as if it were followed by an

29574

end-of-file mark. This method may be redefined by a derived class to

29575

define additional processing at the end of the input, but the

29576

redefined version should always call the HTMLParser base class

29577

method close().</description>

29578

29579

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

29580

29581

29582

<description>Return current line number and offset.</description>

29583

29584

<insert>getpos()</insert><dialog title="Insert getpos">getpos()</dialog><info title="Info window"></info></function>

29585

29586

29587

<description>Return the text of the most recently opened start tag. This should

29588

not normally be needed for structured processing, but may be useful in

29589

dealing with HTML ``as deployed'' or for re-generating input with

29590

minimal changes (whitespace between attributes can be preserved,

29591

etc.).</description>

29592

29593

<insert>get_starttag_text()</insert><dialog title="Insert get_starttag_text">get_starttag_text()</dialog><info title="Info window"></info></function>

29594

29595

29596

<description>This method is called to handle the start of a tag. It is intended to

29597

be overridden by a derived class; the base class implementation does

29598

nothing. The tag argument is the name of the tag converted to

29599

lower case. The attrs argument is a list of (name,

29600

value) pairs containing the attributes found inside the tag's

29601

<> brackets. The name will be translated to lower case

29602

and double quotes and backslashes in the value have been

29603

interpreted. For instance, for the tag <A

29604

HREF="http://www.cwi.nl/">, this method would be called as

29605

handle_starttag('a', [('href', 'http://www.cwi.nl/')]).</description>

29606

<param name="tag" optional="0">tag</param><param name="attrs attrs" optional="0">attrs attrs</param>

29607

<insert>handle_starttag(tag, attrs attrs)</insert><dialog title="Insert handle_starttag">handle_starttag(%0, %1)</dialog><info title="Info window"></info></function>

29608

29609

29610

<description>Similar to handle_starttag(), but called when the parser

29611

encounters an XHTML-style empty tag (<a .../>). This method

29612

may be overridden by subclasses which require this particular lexical

29613

information; the default implementation simple calls

29614

handle_starttag() and handle_endtag().</description>

29615

<param name="tag" optional="0">tag</param><param name="attrs attrs" optional="0">attrs attrs</param>

29616

<insert>handle_startendtag(tag, attrs attrs)</insert><dialog title="Insert handle_startendtag">handle_startendtag(%0, %1)</dialog><info title="Info window"></info></function>

29617

29618

29619

<description>This method is called to handle the end tag of an element. It is

29620

intended to be overridden by a derived class; the base class

29621

implementation does nothing. The tag argument is the name of

29622

the tag converted to lower case.</description>

29623

<param name="tagtag" optional="0">tagtag</param>

29624

<insert>handle_endtag(tagtag)</insert><dialog title="Insert handle_endtag">handle_endtag(%0)</dialog><info title="Info window"></info></function>

29625

29626

29627

<description>This method is called to process arbitrary data. It is intended to be

29628

overridden by a derived class; the base class implementation does

29629

nothing.</description>

29630

<param name="datadata" optional="0">datadata</param>

29631

<insert>handle_data(datadata)</insert><dialog title="Insert handle_data">handle_data(%0)</dialog><info title="Info window"></info></function>

29632

29633

29634

<description>This method is called to

29635

process a character reference of the form #ref;. It

29636

is intended to be overridden by a derived class; the base class

29637

implementation does nothing.</description>

29638

<param name="namename" optional="0">namename</param>

29639

<insert>handle_charref(namename)</insert><dialog title="Insert handle_charref">handle_charref(%0)</dialog><info title="Info window"></info></function>

29640

29641

29642

<description>This method is called to process a general entity reference of the

29643

form &name; where name is an general entity

29644

reference. It is intended to be overridden by a derived class; the

29645

base class implementation does nothing.</description>

29646

<param name="namename" optional="0">namename</param>

29647

<insert>handle_entityref(namename)</insert><dialog title="Insert handle_entityref">handle_entityref(%0)</dialog><info title="Info window"></info></function>

29648

29649

29650

<description>This method is called when a comment is encountered. The

29651

comment argument is a string containing the text between the

29652

{-}{-} and {-}{-} delimiters, but not the delimiters

29653

themselves. For example, the comment <!{-}{-}text{-}{-}> will

29654

cause this method to be called with the argument 'text'. It is

29655

intended to be overridden by a derived class; the base class

29656

implementation does nothing.</description>

29657

<param name="datadata" optional="0">datadata</param>

29658

<insert>handle_comment(datadata)</insert><dialog title="Insert handle_comment">handle_comment(%0)</dialog><info title="Info window"></info></function>

29659

29660

29661

<description>Method called when an SGML declaration is read by the parser. The

29662

decl parameter will be the entire contents of the declaration

29663

inside the <!...> markup.It is intended to be overridden

29664

by a derived class; the base class implementation does nothing.</description>

29665

<param name="decldecl" optional="0">decldecl</param>

29666

<insert>handle_decl(decldecl)</insert><dialog title="Insert handle_decl">handle_decl(%0)</dialog><info title="Info window"></info></function>

29667

29668

29669

<description>Method called when a processing instruction is encountered. The

29670

data parameter will contain the entire processing instruction.

29671

For example, for the processing instruction <?proc color='red'>,

29672

this method would be called as handle_pi("proc color='red'"). It

29673

is intended to be overridden by a derived class; the base class

29674

implementation does nothing.

29675

The HTMLParser class uses the SGML syntactic rules for

29676

processing instruction. An XHTML processing instruction using the

29677

trailing ? will cause the ? to be included in

29678

data.</description>

29679

<param name="datadata" optional="0">datadata</param>

29680

<insert>handle_pi(datadata)</insert><dialog title="Insert handle_pi">handle_pi(%0)</dialog><info title="Info window"></info></function>

29681

29682

29683

</group>

29684

</group>

29685

29686

<description>Only as much of an SGML parser as needed to parse HTML.

29687

</description>

29688

29689

<description>The SGMLParser class is instantiated without arguments.

29690

The parser is hardcoded to recognize the following

29691

constructs:

29692

Opening and closing tags of the form

29693

<tag attr="value" ...> and

29694

</tag>, respectively.

29695

Numeric character references of the form #name;.

29696

Entity references of the form &name;.

29697

SGML comments of the form . Note that

29698

spaces, tabs, and newlines are allowed between the trailing

29699

> and the immediately preceding --.

29700

</description>

29701

29702

<insert>SGMLParser()</insert><dialog title="Insert SGMLParser">SGMLParser()</dialog><info title="Info window"></info></function>

29703

29704

29705

<description>Reset the instance. Loses all unprocessed data. This is called

29706

implicitly at instantiation time.</description>

29707

29708

<insert>reset()</insert><dialog title="Insert reset">reset()</dialog><info title="Info window"></info></function>

29709

29710

29711

<description>Stop processing tags. Treat all following input as literal input

29712

(CDATA). (This is only provided so the HTML tag

29713

<PLAINTEXT> can be implemented.)</description>

29714

29715

<insert>setnomoretags()</insert><dialog title="Insert setnomoretags">setnomoretags()</dialog><info title="Info window"></info></function>

29716

29717

29718

<description>Enter literal mode (CDATA mode).</description>

29719

29720

<insert>setliteral()</insert><dialog title="Insert setliteral">setliteral()</dialog><info title="Info window"></info></function>

29721

29722

29723

<description>Feed some text to the parser. It is processed insofar as it consists

29724

of complete elements; incomplete data is buffered until more data is

29725

fed or close() is called.</description>

29726

<param name="datadata" optional="0">datadata</param>

29727

<insert>feed(datadata)</insert><dialog title="Insert feed">feed(%0)</dialog><info title="Info window"></info></function>

29728

29729

29730

<description>Force processing of all buffered data as if it were followed by an

29731

end-of-file mark. This method may be redefined by a derived class to

29732

define additional processing at the end of the input, but the

29733

redefined version should always call close().</description>

29734

29735

<insert>close()</insert><dialog title="Insert close">close()</dialog><info title="Info window"></info></function>

29736

29737

29738

<description>Return the text of the most recently opened start tag. This should

29739

not normally be needed for structured processing, but may be useful in

29740

dealing with HTML ``as deployed'' or for re-generating input with

29741

minimal changes (whitespace between attributes can be preserved,

29742

etc.).</description>

29743

29744

<insert>get_starttag_text()</insert><dialog title="Insert get_starttag_text">get_starttag_text()</dialog><info title="Info window"></info></function>

29745

29746

29747

<description>This method is called to handle start tags for which either a

29748

start_tag() or do_tag() method has been

29749

defined. The tag argument is the name of the tag converted to

29750

lower case, and the method argument is the bound method which

29751

should be used to support semantic interpretation of the start tag.

29752

The attributes argument is a list of (name,

29753

value) pairs containing the attributes found inside the tag's

29754

<> brackets. The name has been translated to lower case

29755

and double quotes and backslashes in the value have been interpreted.

29756

For instance, for the tag <A HREF="http://www.cwi.nl/">, this

29757

method would be called as unknown_starttag('a', [('href',

29758

'http://www.cwi.nl/')]). The base implementation simply calls

29759

method with attributes as the only argument.</description>

29760

<param name="tag" optional="0">tag</param><param name="method" optional="0">method</param><param name="attributes attributes" optional="0">attributes attributes</param>

29761

<insert>handle_starttag(tag, method, attributes attributes)</insert><dialog title="Insert handle_starttag">handle_starttag(%0, %1, %2)</dialog><info title="Info window"></info></function>

29762

29763

29764

<description>This method is called to handle endtags for which an

29765

end_tag() method has been defined. The

29766

tag argument is the name of the tag converted to lower case, and

29767

the method argument is the bound method which should be used to

29768

support semantic interpretation of the end tag. If no

29769

end_tag() method is defined for the closing element,

29770

this handler is not called. The base implementation simply calls

29771

method.</description>

29772

<param name="tag" optional="0">tag</param><param name="method method" optional="0">method method</param>

29773

<insert>handle_endtag(tag, method method)</insert><dialog title="Insert handle_endtag">handle_endtag(%0, %1)</dialog><info title="Info window"></info></function>

29774

29775

29776

<description>This method is called to process arbitrary data. It is intended to be

29777

overridden by a derived class; the base class implementation does

29778

nothing.</description>

29779

<param name="datadata" optional="0">datadata</param>

29780

<insert>handle_data(datadata)</insert><dialog title="Insert handle_data">handle_data(%0)</dialog><info title="Info window"></info></function>

29781

29782

29783

<description>This method is called to process a character reference of the form

29784

#ref;. In the base implementation, ref must

29785

be a decimal number in the

29786

range 0-255. It translates the character to ASCII and calls the

29787

method handle_data() with the character as argument. If

29788

ref is invalid or out of range, the method

29789

unknown_charref(ref) is called to handle the error. A

29790

subclass must override this method to provide support for named

29791

character entities.</description>

29792

<param name="refref" optional="0">refref</param>

29793

<insert>handle_charref(refref)</insert><dialog title="Insert handle_charref">handle_charref(%0)</dialog><info title="Info window"></info></function>

29794

29795

29796

<description>This method is called to process a general entity reference of the

29797

form &ref; where ref is an general entity

29798

reference. It looks for ref in the instance (or class)

29799

variable entitydefs which should be a mapping from entity

29800

names to corresponding translations. If a translation is found, it

29801

calls the method handle_data() with the translation;

29802

otherwise, it calls the method unknown_entityref(ref).

29803

The default entitydefs defines translations for

29804

;, , ;, ;, and

29805

;.</description>

29806

<param name="refref" optional="0">refref</param>

29807

<insert>handle_entityref(refref)</insert><dialog title="Insert handle_entityref">handle_entityref(%0)</dialog><info title="Info window"></info></function>

29808

29809

29810

<description>This method is called when a comment is encountered. The

29811

comment argument is a string containing the text between the

29812

delimiters, but not the delimiters

29813

themselves. For example, the comment  will

29814

cause this method to be called with the argument 'text'. The

29815

default method does nothing.</description>

29816

<param name="commentcomment" optional="0">commentcomment</param>

29817

<insert>handle_comment(commentcomment)</insert><dialog title="Insert handle_comment">handle_comment(%0)</dialog><info title="Info window"></info></function>

29818

29819

29820

<description>Method called when an SGML declaration is read by the parser. In

29821

practice, the DOCTYPE declaration is the only thing observed in

29822

HTML, but the parser does not discriminate among different (or broken)

29823

declarations. Internal subsets in a DOCTYPE declaration are

29824

not supported. The data parameter will be the entire contents

29825

of the declaration inside the <!...> markup. The

29826

default implementation does nothing.</description>

29827

<param name="datadata" optional="0">datadata</param>

29828

<insert>handle_decl(datadata)</insert><dialog title="Insert handle_decl">handle_decl(%0)</dialog><info title="Info window"></info></function>

29829

29830

29831

<description>This method is called when an end tag is found which does not

29832

correspond to any open element.</description>

29833

<param name="tagtag" optional="0">tagtag</param>

29834

<insert>report_unbalanced(tagtag)</insert><dialog title="Insert report_unbalanced">report_unbalanced(%0)</dialog><info title="Info window"></info></function>

29835

29836

29837

<description>This method is called to process an unknown start tag. It is intended

29838

to be overridden by a derived class; the base class implementation

29839

does nothing.</description>

29840

<param name="tag" optional="0">tag</param><param name="attributes attributes" optional="0">attributes attributes</param>

29841

<insert>unknown_starttag(tag, attributes attributes)</insert><dialog title="Insert unknown_starttag">unknown_starttag(%0, %1)</dialog><info title="Info window"></info></function>

29842

29843

29844

<description>This method is called to process an unknown end tag. It is intended

29845

to be overridden by a derived class; the base class implementation

29846

does nothing.</description>

29847

<param name="tagtag" optional="0">tagtag</param>

29848

<insert>unknown_endtag(tagtag)</insert><dialog title="Insert unknown_endtag">unknown_endtag(%0)</dialog><info title="Info window"></info></function>

29849

29850

29851

<description>This method is called to process unresolvable numeric character

29852

references. Refer to handle_charref() to determine what is

29853

handled by default. It is intended to be overridden by a derived

29854

class; the base class implementation does nothing.</description>

29855

<param name="refref" optional="0">refref</param>

29856

<insert>unknown_charref(refref)</insert><dialog title="Insert unknown_charref">unknown_charref(%0)</dialog><info title="Info window"></info></function>

29857

29858

29859

<description>This method is called to process an unknown entity reference. It is

29860

intended to be overridden by a derived class; the base class

29861

implementation does nothing.</description>

29862

<param name="refref" optional="0">refref</param>

29863

<insert>unknown_entityref(refref)</insert><dialog title="Insert unknown_entityref">unknown_entityref(%0)</dialog><info title="Info window"></info></function>

29864

29865

</group>

29866

29867

<description>A parser for HTML documents.

29868

</description>

29869

29870

<description>This is the basic HTML parser class. It supports all entity names

29871

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>

29872

<param name="formatterformatter" optional="0">formatterformatter</param>

29873

<insert>HTMLParser(formatterformatter)</insert><dialog title="Insert HTMLParser">HTMLParser(%0)</dialog><info title="Info window"></info></function>

29874

29875

29876

<description>In addition to tag methods, the HTMLParser class provides some

29877

additional methods and instance variables for use within tag methods.

29878

{formatter}

29879

This is the formatter instance associated with the parser.

29880

{nofill}

29881

Boolean flag which should be true when whitespace should not be

29882

collapsed, or false when it should be. In general, this should only

29883

be true when character data is to be treated as ``preformatted'' text,

29884

as within a <PRE> element. The default value is false. This

29885

affects the operation of handle_data() and save_end().

29886

</description>

29887

29888

<description>This method is called at the start of an anchor region. The arguments

29889

correspond to the attributes of the <A> tag with the same

29890

names. The default implementation maintains a list of hyperlinks

29891

(defined by the HREF attribute for <A> tags) within the

29892

document. The list of hyperlinks is available as the data attribute

29893

anchorlist.</description>

29894

29895

<insert>anchor_bgn(href, name, type type)</insert><dialog title="Insert anchor_bgn">anchor_bgn(%0, %1, %2)</dialog><info title="Info window"></info></function>

29896

29897

29898

<description>This method is called at the end of an anchor region. The default

29899

implementation adds a textual footnote marker using an index into the

29900

list of hyperlinks created by anchor_bgn().</description>

29901

29902

<insert>anchor_end()</insert><dialog title="Insert anchor_end">anchor_end()</dialog><info title="Info window"></info></function>

29903

29904

29905

<description>This method is called to handle images. The default implementation

29906

simply passes the alt value to the handle_data()

29907

method.</description>

29908

<param name="source" optional="0">source</param><param name="alt" optional="0">alt</param><param name="ismap" optional="1">ismap</param><param name="align" optional="1">align</param><param name="width" optional="1">width</param><param name="height" optional="1">height</param>

29909

<insert>handle_image(source, alt, [ismap], [align], [width], [height])</insert><dialog title="Insert handle_image">handle_image(%0, %1, %2, %3, %4, %5)</dialog><info title="Info window"></info></function>

29910

29911

29912

<description>Begins saving character data in a buffer instead of sending it to the

29913

formatter object. Retrieve the stored data via save_end().

29914

Use of the save_bgn() / save_end() pair may not be

29915

nested.</description>

29916

29917

29918

29919

29920

<description>Ends buffering character data and returns all data saved since the

29921

preceding call to save_bgn(). If the nofill flag is

29922

false, whitespace is collapsed to single spaces. A call to this

29923

method without a preceding call to save_bgn() will raise a

29924

TypeError exception.</description>

29925

29926

29927

29928

</group>

29929

</group>

29930

29931

<description>% Markup notes:

29932

%

29933

% Many of the attributes of the XMLParser objects are callbacks.

29934

% Since signature information must be presented, these are described

29935

% using the methoddesc environment. Since they are attributes which

29936

% are set by client code, in-text references to these attributes

29937

% should be marked using the macro and should not include the

29938

% parentheses used when marking functions and methods.

29939

An interface to the Expat non-validating XML parser.

29940

New in version 2.0

29941

The xml.parsers.expat module is a Python interface to the

29942

Expat</description>

29943

29944

<description>Returns an explanatory string for a given error number errno.</description>

29945

<param name="errnoerrno" optional="0">errnoerrno</param>

29946

<insert>ErrorString(errnoerrno)</insert><dialog title="Insert ErrorString">ErrorString(%0)</dialog><info title="Info window"></info></function>

29947

29948

29949

<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

29950

Python does, and its repertoire of encodings can't be extended; it

29951

supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII. If

29952

encoding is given it will override the implicit or explicit

29953

encoding of the document.

29954

Expat can optionally do XML namespace processing for you, enabled by

29955

providing a value for namespace_separator. The value must be a

29956

one-character string; a ValueError will be raised if the

29957

string has an illegal length (None is considered the same as

29958

omission). When namespace processing is enabled, element type names

29959

and attribute names that belong to a namespace will be expanded. The

29960

element name passed to the element handlers

29961

StartElementHandler and EndElementHandler

29962

will be the concatenation of the namespace URI, the namespace

29963

separator character, and the local part of the name. If the namespace

29964

separator is a zero byte (chr(0)) then the namespace URI and

29965

the local part will be concatenated without any separator.

29966

For example, if namespace_separator is set to a space character

29967

( ) and the following document is parsed:

29968

<?xml version="1.0"?>

29969

<root xmlns = "http://default-namespace.org/"

29970

xmlns:py = "http://www.python.org/ns/">

29971

<py:elem1 />

29972

29973

</root>

29974

StartElementHandler will receive the following strings

29975

for each element:

29976

http://default-namespace.org/ root

29977

http://www.python.org/ns/ elem1

29978

elem2

29979

</description>

29980

<param name="encoding" optional="0">encoding</param><param name="namespace_separator" optional="1">namespace_separator</param>

29981

<insert>ParserCreate(encoding, [namespace_separator])</insert><dialog title="Insert ParserCreate">ParserCreate(%0, %1)</dialog><info title="Info window"></info></function>

29982

29983

29984

<description>xmlparser objects have the following methods:

29985

</description>

29986

29987

<description>Parses the contents of the string data, calling the appropriate

29988

handler functions to process the parsed data. isfinal must be

29989

true on the final call to this method. data can be the empty

29990

string at any time.</description>

29991

<param name="data" optional="0">data</param><param name="isfinal" optional="1">isfinal</param>

29992

<insert>Parse(data, [isfinal])</insert><dialog title="Insert Parse">Parse(%0, %1)</dialog><info title="Info window"></info></function>

29993

29994

29995

<description>Parse XML data reading from the object file. file only

29996

needs to provide the read(nbytes) method, returning the

29997

empty string when there's no more data.</description>

29998

<param name="filefile" optional="0">filefile</param>

29999

<insert>ParseFile(filefile)</insert><dialog title="Insert ParseFile">ParseFile(%0)</dialog><info title="Info window"></info></function>

30000

30001

30002

<description>Sets the base to be used for resolving relative URIs in system

30003

identifiers in declarations. Resolving relative identifiers is left

30004

to the application: this value will be passed through as the

30005

base argument to the ExternalEntityRefHandler,

30006

NotationDeclHandler, and

30007

UnparsedEntityDeclHandler functions.</description>

30008

<param name="basebase" optional="0">basebase</param>

30009

<insert>SetBase(basebase)</insert><dialog title="Insert SetBase">SetBase(%0)</dialog><info title="Info window"></info></function>

30010

30011

30012

<description>Returns a string containing the base set by a previous call to

30013

SetBase(), or None if SetBase() hasn't been called.</description>

30014

30015

<insert>GetBase()</insert><dialog title="Insert GetBase">GetBase()</dialog><info title="Info window"></info></function>

30016

30017

30018

<description>Returns the input data that generated the current event as a string.

30019

The data is in the encoding of the entity which contains the text.

30020

When called while an event handler is not active, the return value is

30021

None.

30022

New in version 2.1</description>

30023

30024

<insert>GetInputContext()</insert><dialog title="Insert GetInputContext">GetInputContext()</dialog><info title="Info window"></info></function>

30025

30026

30027

<description>Create a ``child'' parser which can be used to parse an external

30028

parsed entity referred to by content parsed by the parent parser. The

30029

context parameter should be the string passed to the

30030

ExternalEntityRefHandler() handler function, described below.

30031

The child parser is created with the ordered_attributes,

30032

returns_unicode and specified_attributes set to the

30033

values of this parser.</description>

30034

<param name="context" optional="0">context</param><param name="encoding" optional="1">encoding</param>

30035

<insert>ExternalEntityParserCreate(context, [encoding])</insert><dialog title="Insert ExternalEntityParserCreate">ExternalEntityParserCreate(%0, %1)</dialog><info title="Info window"></info></function>

30036

30037

30038

<description>Called when the XML declaration is parsed. The XML declaration is the

30039

(optional) declaration of the applicable version of the XML

30040

recommendation, the encoding of the document text, and an optional

30041

``standalone'' declaration. version and encoding will be

30042

strings of the type dictated by the returns_unicode

30043

attribute, and standalone will be 1 if the document is

30044

declared standalone, 0 if it is declared not to be standalone,

30045

or -1 if the standalone clause was omitted.

30046

This is only available with Expat version 1.95.0 or newer.

30047

New in version 2.1</description>

30048

<param name="version" optional="0">version</param><param name="encoding" optional="0">encoding</param><param name="standalone standalone" optional="0">standalone standalone</param>

30049

<insert>XmlDeclHandler(version, encoding, standalone standalone)</insert><dialog title="Insert XmlDeclHandler">XmlDeclHandler(%0, %1, %2)</dialog><info title="Info window"></info></function>

30050

30051

30052

<description>Called when Expat begins parsing the document type declaration

30053

(<!DOCTYPE ...). The doctypeName is provided exactly

30054

as presented. The systemId and publicId parameters give

30055

the system and public identifiers if specified, or None if

30056

omitted. has_internal_subset will be true if the document

30057

contains and internal document declaration subset.

30058

This requires Expat version 1.2 or newer.</description>

30059

<param name="doctypeName" optional="0">doctypeName</param><param name="systemId" optional="0">systemId</param><param name="publicId" optional="0">publicId</param><param name="has_internal_subset

30060

has_internal_subset" optional="0">has_internal_subset

30061

has_internal_subset</param>

30062

<insert>StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset

30063

has_internal_subset)</insert><dialog title="Insert StartDoctypeDeclHandler">StartDoctypeDeclHandler(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

30064

30065

30066

<description>Called when Expat is done parsing the document type delaration.

30067

This requires Expat version 1.2 or newer.</description>

30068

30069

<insert>EndDoctypeDeclHandler()</insert><dialog title="Insert EndDoctypeDeclHandler">EndDoctypeDeclHandler()</dialog><info title="Info window"></info></function>

30070

30071

30072

<description>Called once for each element type declaration. name is the name

30073

of the element type, and model is a representation of the

30074

content model.</description>

30075

<param name="name" optional="0">name</param><param name="model model" optional="0">model model</param>

30076

<insert>ElementDeclHandler(name, model model)</insert><dialog title="Insert ElementDeclHandler">ElementDeclHandler(%0, %1)</dialog><info title="Info window"></info></function>

30077

30078

30079

<description>Called for each declared attribute for an element type. If an

30080

attribute list declaration declares three attributes, this handler is

30081

called three times, once for each attribute. elname is the name

30082

of the element to which the declaration applies and attname is

30083

the name of the attribute declared. The attribute type is a string

30084

passed as type; the possible values are 'CDATA',

30085

'ID', 'IDREF', ...

30086

default gives the default value for the attribute used when the

30087

attribute is not specified by the document instance, or None if

30088

there is no default value ( values). If the attribute

30089

is required to be given in the document instance, required will

30090

be true.

30091

This requires Expat version 1.95.0 or newer.</description>

30092

<param name="elname" optional="0">elname</param><param name="attname" optional="0">attname</param><param name="type" optional="0">type</param><param name="default" optional="0">default</param><param name="required required" optional="0">required required</param>

30093

<insert>AttlistDeclHandler(elname, attname, type, default, required required)</insert><dialog title="Insert AttlistDeclHandler">AttlistDeclHandler(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

30094

30095

30096

<description>Called for the start of every element. name is a string

30097

containing the element name, and attributes is a dictionary

30098

mapping attribute names to their values.</description>

30099

<param name="name" optional="0">name</param><param name="attributes attributes" optional="0">attributes attributes</param>

30100

<insert>StartElementHandler(name, attributes attributes)</insert><dialog title="Insert StartElementHandler">StartElementHandler(%0, %1)</dialog><info title="Info window"></info></function>

30101

30102

30103

<description>Called for the end of every element.</description>

30104

<param name="namename" optional="0">namename</param>

30105

<insert>EndElementHandler(namename)</insert><dialog title="Insert EndElementHandler">EndElementHandler(%0)</dialog><info title="Info window"></info></function>

30106

30107

30108

<description>Called for every processing instruction.</description>

30109

<param name="target" optional="0">target</param><param name="data data" optional="0">data data</param>

30110

<insert>ProcessingInstructionHandler(target, data data)</insert><dialog title="Insert ProcessingInstructionHandler">ProcessingInstructionHandler(%0, %1)</dialog><info title="Info window"></info></function>

30111

30112

30113

<description>Called for character data. This will be called for normal character

30114

data, CDATA marked content, and ignorable whitespace. Applications

30115

which must distinguish these cases can use the

30116

StartCdataSectionHandler, EndCdataSectionHandler,

30117

and ElementDeclHandler callbacks to collect the required

30118

information.</description>

30119

<param name="datadata" optional="0">datadata</param>

30120

<insert>CharacterDataHandler(datadata)</insert><dialog title="Insert CharacterDataHandler">CharacterDataHandler(%0)</dialog><info title="Info window"></info></function>

30121

30122

30123

<description>Called for unparsed (NDATA) entity declarations. This is only present

30124

for version 1.2 of the Expat library; for more recent versions, use

30125

EntityDeclHandler instead. (The underlying function in the

30126

Expat library has been declared obsolete.)</description>

30127

<param name="entityName" optional="0">entityName</param><param name="base" optional="0">base</param><param name="systemId" optional="0">systemId</param><param name="publicId" optional="0">publicId</param><param name="notationName

30128

notationName" optional="0">notationName

30129

notationName</param>

30130

<insert>UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName

30131

notationName)</insert><dialog title="Insert UnparsedEntityDeclHandler">UnparsedEntityDeclHandler(%0, %1, %2, %3, %4)</dialog><info title="Info window"></info></function>

30132

30133

30134

<description>Called for all entity declarations. For parameter and internal

30135

entities, value will be a string giving the declared contents

30136

of the entity; this will be None for external entities. The

30137

notationName parameter will be None for parsed entities,

30138

and the name of the notation for unparsed entities.

30139

is_parameter_entity will be true if the entity is a paremeter

30140

entity or false for general entities (most applications only need to

30141

be concerned with general entities).

30142

This is only available starting with version 1.95.0 of the Expat

30143

library.

30144

New in version 2.1</description>

30145

<param name="entityName" optional="0">entityName</param><param name="is_parameter_entity" optional="0">is_parameter_entity</param><param name="value" optional="0">value</param><param name="base" optional="0">base</param><param name="systemId" optional="0">systemId</param><param name="publicId" optional="0">publicId</param><param name="notationName

30146

notationName" optional="0">notationName

30147

notationName</param>

30148

<insert>EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName

30149

notationName)</insert><dialog title="Insert EntityDeclHandler">EntityDeclHandler(%0, %1, %2, %3, %4, %5, %6)</dialog><info title="Info window"></info></function>

30150

30151

30152

<description>Called for notation declarations. notationName, base, and

30153

systemId, and publicId are strings if given. If the

30154

public identifier is omitted, publicId will be None.</description>

30155

<param name="notationName" optional="0">notationName</param><param name="base" optional="0">base</param><param name="systemId" optional="0">systemId</param><param name="publicId publicId" optional="0">publicId publicId</param>

30156

<insert>NotationDeclHandler(notationName, base, systemId, publicId publicId)</insert><dialog title="Insert NotationDeclHandler">NotationDeclHandler(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

30157

30158

30159

<description>Called when an element contains a namespace declaration. Namespace

30160

declarations are processed before the StartElementHandler is

30161

called for the element on which declarations are placed.</description>

30162

<param name="prefix" optional="0">prefix</param><param name="uri uri" optional="0">uri uri</param>

30163

<insert>StartNamespaceDeclHandler(prefix, uri uri)</insert><dialog title="Insert StartNamespaceDeclHandler">StartNamespaceDeclHandler(%0, %1)</dialog><info title="Info window"></info></function>

30164

30165

30166

<description>Called when the closing tag is reached for an element that contained a namespace declaration. This is called once for each

30167

namespace declaration on the element in the reverse of the order for

30168

which the StartNamespaceDeclHandler was called to indicate

30169

the start of each namespace declaration's scope. Calls to this

30170

handler are made after the corresponding EndElementHandler

30171

for the end of the element.</description>

30172

<param name="prefixprefix" optional="0">prefixprefix</param>

30173

<insert>EndNamespaceDeclHandler(prefixprefix)</insert><dialog title="Insert EndNamespaceDeclHandler">EndNamespaceDeclHandler(%0)</dialog><info title="Info window"></info></function>

30174

30175

30176

<description>Called for comments. data is the text of the comment, excluding

30177

the leading `'.</description>

30178

<param name="datadata" optional="0">datadata</param>

30179

<insert>CommentHandler(datadata)</insert><dialog title="Insert CommentHandler">CommentHandler(%0)</dialog><info title="Info window"></info></function>

30180

30181

30182

<description>Called at the start of a CDATA section. This and

30183

StartCdataSectionHandler are needed to be able to identify

30184

the syntactical start and end for CDATA sections.</description>

30185

30186

<insert>StartCdataSectionHandler()</insert><dialog title="Insert StartCdataSectionHandler">StartCdataSectionHandler()</dialog><info title="Info window"></info></function>

30187

30188

30189

<description>Called at the end of a CDATA section.</description>

30190

30191

<insert>EndCdataSectionHandler()</insert><dialog title="Insert EndCdataSectionHandler">EndCdataSectionHandler()</dialog><info title="Info window"></info></function>

30192

30193

30194

<description>Called for any characters in the XML document for

30195

which no applicable handler has been specified. This means

30196

characters that are part of a construct which could be reported, but

30197

for which no handler has been supplied.</description>

30198

<param name="datadata" optional="0">datadata</param>

30199

<insert>DefaultHandler(datadata)</insert><dialog title="Insert DefaultHandler">DefaultHandler(%0)</dialog><info title="Info window"></info></function>

30200

30201

30202

<description>This is the same as the DefaultHandler, but doesn't inhibit expansion of internal entities.

30203

The entity reference will not be passed to the default handler.</description>

30204

<param name="datadata" optional="0">datadata</param>

30205

<insert>DefaultHandlerExpand(datadata)</insert><dialog title="Insert DefaultHandlerExpand">DefaultHandlerExpand(%0)</dialog><info title="Info window"></info></function>

30206

30207

30208

<description>Called if the

30209

XML document hasn't been declared as being a standalone document.

30210

This happens when there is an external subset or a reference to a

30211

parameter entity, but the XML declaration does not set standalone to

30212

yes in an XML declaration. If this handler returns 0,

30213

then the parser will throw an XML_ERROR_NOT_STANDALONE

30214

error. If this handler is not set, no exception is raised by the

30215

parser for this condition.</description>

30216

30217

<insert>NotStandaloneHandler()</insert><dialog title="Insert NotStandaloneHandler">NotStandaloneHandler()</dialog><info title="Info window"></info></function>

30218

30219

30220

<description>Called for references to external entities. base is the current

30221

base, as set by a previous call to SetBase(). The public and

30222

system identifiers, systemId and publicId, are strings if

30223

given; if the public identifier is not given, publicId will be

30224

None. The context value is opaque and should only be

30225

used as described below.

30226

For external entities to be parsed, this handler must be implemented.

30227

It is responsible for creating the sub-parser using

30228

ExternalEntityParserCreate(context), initializing it with

30229

the appropriate callbacks, and parsing the entity. This handler

30230

should return an integer; if it returns 0, the parser will

30231

throw an XML_ERROR_EXTERNAL_ENTITY_HANDLING error,

30232

otherwise parsing will continue.

30233

If this handler is not provided, external entities are reported by the

30234

DefaultHandler callback, if provided.</description>

30235

<param name="context" optional="0">context</param><param name="base" optional="0">base</param><param name="systemId" optional="0">systemId</param><param name="publicId publicId" optional="0">publicId publicId</param>

30236

<insert>ExternalEntityRefHandler(context, base, systemId, publicId publicId)</insert><dialog title="Insert ExternalEntityRefHandler">ExternalEntityRefHandler(%0, %1, %2, %3)</dialog><info title="Info window"></info></function>

30237

30238

</group>

30239

30240

<description>ExpatError exceptions have a number of interesting

30241

attributes:

30242

[ExpatError]{code}

30243

Expat's internal error number for the specific error. This will

30244

match one of the constants defined in the errors object from

30245

this module.

30246

New in version 2.1

30247

[ExpatError]{lineno}

30248

Line number on which the error was detected. The first line is

30249

numbered 1.

30250

New in version 2.1

30251

[ExpatError]{offset}

30252

Character offset into the line where the error occurred. The first

30253

column is numbered 0.

30254

New in version 2.1

30255

</description>

30256

</group>

30257

30258

<description>The following program defines three handlers that just print out their

30259

arguments.

30260

import xml.parsers.expat

30261

# 3 handler functions

30262

def start_element(name, attrs):

30263

print 'Start element:', name, attrs

30264

def end_element(name):

30265

print 'End element:', name

30266

def char_data(data):

30267

print 'Character data:', repr(data)

30268

p = xml.parsers.expat.ParserCreate()

30269

p.StartElementHandler = start_element

30270

p.EndElementHandler = end_element

30271

p.CharacterDataHandler = char_data

30272

p.Parse("""<?xml version="1.0"?>

30273

30274

30275

</parent>""", 1)

30276

The output from this program is:

30277

Start element: parent {'id': 'top'}

30278

Start element: child1 {'name': 'paul'}

30279

Character data: 'Text goes here'

30280

End element: child1

30281

Character data: ''

30282

Start element: child2 {'name': 'fred'}

30283

Character data: 'More text'

30284

End element: child2

30285

Character data: ''

30286

End element: parent

30287

</description>

30288

</group>

30289

30290

<description>Content modules are described using nested tuples. Each tuple

30291

contains four values: the type, the quantifier, the name, and a tuple

30292

of children. Children are simply additional content module

30293

descriptions.

30294

The values of the first two fields are constants defined in the

30295

model object of the xml.parsers.expat module. These

30296

constants can be collected in two groups: the model type group and the

30297

quantifier group.

30298

The constants in the model type group are:

30299

{XML_CTYPE_ANY}

30300

The element named by the model name was declared to have a content

30301

model of ANY.

30302

{XML_CTYPE_CHOICE}

30303

The named element allows a choice from a number of options; this is

30304

used for content models such as (A | B | C).

30305

{XML_CTYPE_EMPTY}

30306

Elements which are declared to be EMPTY have this model type.

30307

{XML_CTYPE_MIXED}

30308

{XML_CTYPE_NAME}

30309

{XML_CTYPE_SEQ}

30310

Models which represent a series of models which follow one after the

30311

other are indicated with this model type. This is used for models

30312

such as (A, B, C).

30313

The constants in the quantifier group are:

30314

{XML_CQUANT_NONE}

30315

No modifier is given, so it can appear exactly once, as for A.

30316

{XML_CQUANT_OPT}

30317

The model is optional: it can appear once or not at all, as for

30318

A?.

30319

{XML_CQUANT_PLUS}

30320

The model must occur one or more times (like A+).

30321

{XML_CQUANT_REP}

30322

The model must occur zero or more times, as for A*.

30323

</description>

30324

</group>

30325

30326

</group>

30327

</group>

30328

30329

<description>Document Object Model API for Python.

30330

New in version 2.0

30331

The Document Object Model, or ``DOM,'' is a cross-language API from

30332

the World Wide Web Consortium (W3C) for accessing and modifying XML

30333

documents. A DOM implementation presents an XML document as a tree

30334

structure, or allows client code to build such a structure from

30335

scratch. It then gives access to the structure through a set of

30336

objects which provided well-known interfaces.

30337

The DOM is extremely useful for random-access applications. SAX only

30338

allows you a view of one bit of the document at a time. If you are

30339

looking at one SAX element, you have no access to another. If you are

30340

looking at a text node, you have no access to a containing element.

30341

When you write a SAX application, you need to keep track of your

30342

program's position in the document somewhere in your own code. SAX

30343

does not do it for you. Also, if you need to look ahead in the XML

30344

document, you are just out of luck.

30345

Some applications are simply impossible in an event driven model with

30346

no access to a tree. Of course you could build some sort of tree

30347

yourself in SAX events, but the DOM allows you to avoid writing that

30348

code. The DOM is a standard tree representation for XML data.

30349

%What if your needs are somewhere between SAX and the DOM? Perhaps

30350

%you cannot afford to load the entire tree in memory but you find the

30351

%SAX model somewhat cumbersome and low-level. There is also a module

30352

%called xml.dom.pulldom that allows you to build trees of only the

30353

%parts of a document that you need structured access to. It also has

30354

%features that allow you to find your way around the DOM.

30355

% See http://www.prescod.net/python/pulldom

30356

The Document Object Model is being defined by the W3C in stages, or

30357

``levels'' in their terminology. The Python mapping of the API is

30358

substantially based on the DOM Level~2 recommendation. The mapping of

30359

the Level~3 specification, currently only available in draft form, is

30360

being developed by the Python XML Special Interest

30361

Group{http://www.python.org/sigs/xml-sig/} as part of the

30362

PyXML package{http://pyxml.sourceforge.net/}. Refer to the

30363

documentation bundled with that package for information on the current

30364

state of DOM Level~3 support.

30365

DOM applications typically start by parsing some XML into a DOM. How

30366

this is accomplished is not covered at all by DOM Level~1, and Level~2

30367

provides only limited improvements: There is a

30368

DOMImplementation object class which provides access to

30369

Document creation methods, but no way to access an XML

30370

reader/parser/Document builder in an implementation-independent way.

30371

There is also no well-defined way to access these methods without an

30372

existing Document object. In Python, each DOM implementation

30373

will provide a function getDOMImplementation(). DOM Level~3

30374

adds a Load/Store specification, which defines an interface to the

30375

reader, but this is not yet available in the Python standard library.

30376

Once you have a DOM document object, you can access the parts of your

30377

XML document through its properties and methods. These properties are

30378

defined in the DOM specification; this portion of the reference manual

30379

describes the interpretation of the specification in Python.

30380

The specification provided by the W3C defines the DOM API for Java,

30381

ECMAScript, and OMG IDL. The Python mapping defined here is based in

30382

large part on the IDL version of the specification, but strict

30383

compliance is not required (though implementations are free to support

30384

the strict mapping from IDL). See section dom-conformance,

30385

``Conformance,'' for a detailed discussion of mapping requirements.

30386