~milo/+junk/python-linaro : revision 51

1

# DP: hg updates of the 2.7 release branch (until 2012-02-16).

2

3

# hg diff -r v2.7.2 | filterdiff --exclude=Lib/pstats.py --exclude=Lib/profile.py --exclude=.*ignore --exclude=.hg* --remove-timestamps

4

5

diff -r 8527427914a2 Demo/threads/sync.py

6

--- a/Demo/threads/sync.py

7

+++ b/Demo/threads/sync.py

8

@@ -265,7 +265,7 @@

9

# intervening. If there are other threads waiting to write, they

10

# are allowed to proceed only if the current thread calls

11

# .read_out; threads waiting to read are only allowed to proceed

12

-# if there are are no threads waiting to write. (This is a

13

+# if there are no threads waiting to write. (This is a

14

# weakness of the interface!)

15

16

import thread

17

diff -r 8527427914a2 Demo/tix/tixwidgets.py

18

--- a/Demo/tix/tixwidgets.py

19

+++ b/Demo/tix/tixwidgets.py

20

@@ -659,7 +659,7 @@

21

I have implemented a new image type called "compound". It allows you

22

to glue together a bunch of bitmaps, images and text strings together

23

to form a bigger image. Then you can use this image with widgets that

24

-support the -image option. For example, you can display a text string string

25

+support the -image option. For example, you can display a text string

26

together with a bitmap, at the same time, inside a TK button widget.

27

""")

28

list.pack(expand=1, fill=Tix.BOTH, padx=4, pady=6)

29

diff -r 8527427914a2 Demo/turtle/about_turtle.txt

30

--- a/Demo/turtle/about_turtle.txt

31

+++ b/Demo/turtle/about_turtle.txt

32

@@ -7,10 +7,10 @@

33

kids. It was part of the original Logo programming language developed

34

by Wally Feurzig and Seymour Papert in 1966.

35

36

-Imagine a robotic turtle starting at (0, 0) in the x-y plane. Give it

37

+Imagine a robotic turtle starting at (0, 0) in the x-y plane. After an ``import turtle``, give it

38

the command turtle.forward(15), and it moves (on-screen!) 15 pixels in

39

the direction it is facing, drawing a line as it moves. Give it the

40

-command turtle.left(25), and it rotates in-place 25 degrees clockwise.

41

+command turtle.right(25), and it rotates in-place 25 degrees clockwise.

42

43

By combining together these and similar commands, intricate shapes and

44

pictures can easily be drawn.

45

diff -r 8527427914a2 Doc/ACKS.txt

46

--- a/Doc/ACKS.txt

47

+++ b/Doc/ACKS.txt

48

@@ -33,6 +33,7 @@

49

* Keith Briggs

50

* Ian Bruntlett

51

* Lee Busby

52

+ * Arnaud Calmettes

53

* Lorenzo M. Catucci

54

* Carl Cerecke

55

* Mauro Cicognini

56

@@ -77,6 +78,7 @@

57

* Travis B. Hartwell

58

* Tim Hatch

59

* Janko Hauser

60

+ * Ben Hayden

61

* Thomas Heller

62

* Bernhard Herzog

63

* Magnus L. Hetland

64

@@ -103,6 +105,7 @@

65

* Robert Kern

66

* Jim Kerr

67

* Jan Kim

68

+ * Kamil Kisiel

69

* Greg Kochanski

70

* Guido Kollerie

71

* Peter A. Koren

72

@@ -139,7 +142,8 @@

73

* Ross Moore

74

* Sjoerd Mullender

75

* Dale Nagata

76

- * Michal Nowikowski

77

+ * Michal Nowikowski

78

+ * Steffen Daode Nurpmeso

79

* Ng Pheng Siong

80

* Koray Oner

81

* Tomas Oppelstrup

82

@@ -180,6 +184,7 @@

83

* Joakim Sernbrant

84

* Justin Sheehy

85

* Charlie Shepherd

86

+ * Yue Shuaijie

87

* Michael Simcich

88

* Ionel Simionescu

89

* Michael Sloan

90

@@ -197,6 +202,7 @@

91

* Kalle Svensson

92

* Jim Tittsler

93

* David Turner

94

+ * Sandro Tosi

95

* Ville Vainio

96

* Martijn Vries

97

* Charles G. Waldman

98

@@ -214,6 +220,7 @@

99

* Collin Winter

100

* Blake Winton

101

* Dan Wolfe

102

+ * Adam Woodbeck

103

* Steven Work

104

* Thomas Wouters

105

* Ka-Ping Yee

106

diff -r 8527427914a2 Doc/Makefile

107

--- a/Doc/Makefile

108

+++ b/Doc/Makefile

109

@@ -40,7 +40,7 @@

110

checkout:

111

@if [ ! -d tools/sphinx ]; then \

112

echo "Checking out Sphinx..."; \

113

- svn checkout $(SVNROOT)/external/Sphinx-0.6.7/sphinx tools/sphinx; \

114

+ svn checkout $(SVNROOT)/external/Sphinx-1.0.7/sphinx tools/sphinx; \

115

fi

116

@if [ ! -d tools/docutils ]; then \

117

echo "Checking out Docutils..."; \

118

diff -r 8527427914a2 Doc/README.txt

119

--- a/Doc/README.txt

120

+++ b/Doc/README.txt

121

@@ -127,7 +127,7 @@

122

as long as you don't change or remove the copyright notice:

123

124

----------------------------------------------------------------------

125

126

127

128

129

130

diff -r 8527427914a2 Doc/bugs.rst

131

--- a/Doc/bugs.rst

132

+++ b/Doc/bugs.rst

133

@@ -57,12 +57,14 @@

134

135

Each bug report will be assigned to a developer who will determine what needs to

136

be done to correct the problem. You will receive an update each time action is

137

-taken on the bug. See http://www.python.org/dev/workflow/ for a detailed

138

-description of the issue workflow.

139

+taken on the bug.

140

141

142

.. seealso::

143

144

+ `Python Developer's Guide <http://docs.python.org/devguide/>`_

145

+ Detailed description of the issue workflow and developers tools.

146

+

147

`How to Report Bugs Effectively <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_

148

Article which goes into some detail about how to create a useful bug report.

149

This describes what kind of information is useful and why it is useful.

150

diff -r 8527427914a2 Doc/c-api/abstract.rst

151

--- a/Doc/c-api/abstract.rst

152

+++ b/Doc/c-api/abstract.rst

153

@@ -13,7 +13,7 @@

154

will raise a Python exception.

155

156

It is not possible to use these functions on objects that are not properly

157

-initialized, such as a list object that has been created by :cfunc:`PyList_New`,

158

+initialized, such as a list object that has been created by :c:func:`PyList_New`,

159

but whose items have not been set to some non-\ ``NULL`` value yet.

160

161

.. toctree::

162

diff -r 8527427914a2 Doc/c-api/allocation.rst

163

--- a/Doc/c-api/allocation.rst

164

+++ b/Doc/c-api/allocation.rst

165

@@ -6,20 +6,20 @@

166

==============================

167

168

169

-.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)

170

+.. c:function:: PyObject* _PyObject_New(PyTypeObject *type)

171

172

173

-.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)

174

+.. c:function:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)

175

176

.. versionchanged:: 2.5

177

- This function used an :ctype:`int` type for *size*. This might require

178

+ This function used an :c:type:`int` type for *size*. This might require

179

changes in your code for properly supporting 64-bit systems.

180

181

182

-.. cfunction:: void _PyObject_Del(PyObject *op)

183

+.. c:function:: void _PyObject_Del(PyObject *op)

184

185

186

-.. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)

187

+.. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)

188

189

Initialize a newly-allocated object *op* with its type and initial

190

reference. Returns the initialized object. If *type* indicates that the

191

@@ -28,17 +28,17 @@

192

affected.

193

194

195

-.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)

196

+.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)

197

198

- This does everything :cfunc:`PyObject_Init` does, and also initializes the

199

+ This does everything :c:func:`PyObject_Init` does, and also initializes the

200

length information for a variable-size object.

201

202

.. versionchanged:: 2.5

203

- This function used an :ctype:`int` type for *size*. This might require

204

+ This function used an :c:type:`int` type for *size*. This might require

205

changes in your code for properly supporting 64-bit systems.

206

207

208

-.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type)

209

+.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)

210

211

Allocate a new Python object using the C structure type *TYPE* and the

212

Python type object *type*. Fields not defined by the Python object header

213

@@ -47,7 +47,7 @@

214

the type object.

215

216

217

-.. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)

218

+.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)

219

220

Allocate a new Python object using the C structure type *TYPE* and the

221

Python type object *type*. Fields not defined by the Python object header

222

@@ -59,20 +59,20 @@

223

improving the memory management efficiency.

224

225

.. versionchanged:: 2.5

226

- This function used an :ctype:`int` type for *size*. This might require

227

+ This function used an :c:type:`int` type for *size*. This might require

228

changes in your code for properly supporting 64-bit systems.

229

230

231

-.. cfunction:: void PyObject_Del(PyObject *op)

232

+.. c:function:: void PyObject_Del(PyObject *op)

233

234

- Releases memory allocated to an object using :cfunc:`PyObject_New` or

235

- :cfunc:`PyObject_NewVar`. This is normally called from the

236

+ Releases memory allocated to an object using :c:func:`PyObject_New` or

237

+ :c:func:`PyObject_NewVar`. This is normally called from the

238

:attr:`tp_dealloc` handler specified in the object's type. The fields of

239

the object should not be accessed after this call as the memory is no

240

longer a valid Python object.

241

242

243

-.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)

244

+.. c:function:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)

245

246

Create a new module object based on a name and table of functions,

247

returning the new module object.

248

@@ -82,7 +82,7 @@

249

*methods* argument.

250

251

252

-.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)

253

+.. c:function:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)

254

255

Create a new module object based on a name and table of functions,

256

returning the new module object. If *doc* is non-*NULL*, it will be used

257

@@ -93,7 +93,7 @@

258

*methods* argument.

259

260

261

-.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)

262

+.. c:function:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)

263

264

Create a new module object based on a name and table of functions,

265

returning the new module object. If *doc* is non-*NULL*, it will be used

266

@@ -107,7 +107,7 @@

267

.. note::

268

269

Most uses of this function should probably be using the

270

- :cfunc:`Py_InitModule3` instead; only use this if you are sure you need

271

+ :c:func:`Py_InitModule3` instead; only use this if you are sure you need

272

it.

273

274

.. versionchanged:: 2.3

275

@@ -115,7 +115,7 @@

276

*methods* argument.

277

278

279

-.. cvar:: PyObject _Py_NoneStruct

280

+.. c:var:: PyObject _Py_NoneStruct

281

282

Object which is visible in Python as ``None``. This should only be

283

accessed using the ``Py_None`` macro, which evaluates to a pointer to this

284

diff -r 8527427914a2 Doc/c-api/arg.rst

285

--- a/Doc/c-api/arg.rst

286

+++ b/Doc/c-api/arg.rst

287

@@ -9,8 +9,8 @@

288

methods. Additional information and examples are available in

289

:ref:`extending-index`.

290

291

-The first three of these functions described, :cfunc:`PyArg_ParseTuple`,

292

-:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use

293

+The first three of these functions described, :c:func:`PyArg_ParseTuple`,

294

+:c:func:`PyArg_ParseTupleAndKeywords`, and :c:func:`PyArg_Parse`, all use

295

*format strings* which are used to tell the function about the expected

296

arguments. The format strings use the same syntax for each of these

297

functions.

298

@@ -24,6 +24,11 @@

299

that matches the format unit; and the entry in [square] brackets is the type

300

of the C variable(s) whose address should be passed.

301

302

+These formats allow to access an object as a contiguous chunk of memory.

303

+You don't have to provide raw storage for the returned unicode or bytes

304

+area. Also, you won't have to release any memory yourself, except with the

305

+``es``, ``es#``, ``et`` and ``et#`` formats.

306

+

307

``s`` (string or Unicode) [const char \*]

308

Convert a Python string or Unicode object to a C pointer to a character

309

string. You must not provide storage for the string itself; a pointer to

310

@@ -33,7 +38,7 @@

311

raised. Unicode objects are converted to C strings using the default

312

encoding. If this conversion fails, a :exc:`UnicodeError` is raised.

313

314

-``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :ctype:`Py_ssize_t`, see below)]

315

+``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :c:type:`Py_ssize_t`, see below)]

316

This variant on ``s`` stores into two C variables, the first one a pointer

317

to a character string, the second one its length. In this case the Python

318

string may contain embedded null bytes. Unicode objects pass back a

319

@@ -42,8 +47,8 @@

320

a reference to the raw internal data representation.

321

322

Starting with Python 2.5 the type of the length argument can be controlled

323

- by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including

324

- :file:`Python.h`. If the macro is defined, length is a :ctype:`Py_ssize_t`

325

+ by defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including

326

+ :file:`Python.h`. If the macro is defined, length is a :c:type:`Py_ssize_t`

327

rather than an int.

328

329

``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer]

330

@@ -71,14 +76,14 @@

331

Convert a Python Unicode object to a C pointer to a NUL-terminated buffer

332

of 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to

333

provide storage for the Unicode data buffer; a pointer to the existing

334

- Unicode data is stored into the :ctype:`Py_UNICODE` pointer variable whose

335

+ Unicode data is stored into the :c:type:`Py_UNICODE` pointer variable whose

336

address you pass.

337

338

``u#`` (Unicode) [Py_UNICODE \*, int]

339

This variant on ``u`` stores into two C variables, the first one a pointer

340

to a Unicode data buffer, the second one its length. Non-Unicode objects

341

are handled by interpreting their read-buffer pointer as pointer to a

342

- :ctype:`Py_UNICODE` array.

343

+ :c:type:`Py_UNICODE` array.

344

345

``es`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]

346

This variant on ``s`` is used for encoding Unicode and objects convertible

347

@@ -86,18 +91,18 @@

348

embedded NUL bytes.

349

350

This format requires two arguments. The first is only used as input, and

351

- must be a :ctype:`const char\*` which points to the name of an encoding as

352

+ must be a :c:type:`const char\*` which points to the name of an encoding as

353

a NUL-terminated string, or *NULL*, in which case the default encoding is

354

used. An exception is raised if the named encoding is not known to Python.

355

- The second argument must be a :ctype:`char\*\*`; the value of the pointer

356

+ The second argument must be a :c:type:`char\*\*`; the value of the pointer

357

it references will be set to a buffer with the contents of the argument

358

text. The text will be encoded in the encoding specified by the first

359

argument.

360

361

- :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy

362

+ :c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy

363

the encoded data into this buffer and adjust *\*buffer* to reference the

364

newly allocated storage. The caller is responsible for calling

365

- :cfunc:`PyMem_Free` to free the allocated buffer after use.

366

+ :c:func:`PyMem_Free` to free the allocated buffer after use.

367

368

``et`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]

369

Same as ``es`` except that 8-bit string objects are passed through without

370

@@ -110,10 +115,10 @@

371

allows input data which contains NUL characters.

372

373

It requires three arguments. The first is only used as input, and must be

374

- a :ctype:`const char\*` which points to the name of an encoding as a

375

+ a :c:type:`const char\*` which points to the name of an encoding as a

376

NUL-terminated string, or *NULL*, in which case the default encoding is

377

used. An exception is raised if the named encoding is not known to Python.

378

- The second argument must be a :ctype:`char\*\*`; the value of the pointer

379

+ The second argument must be a :c:type:`char\*\*`; the value of the pointer

380

it references will be set to a buffer with the contents of the argument

381

text. The text will be encoded in the encoding specified by the first

382

argument. The third argument must be a pointer to an integer; the

383

@@ -124,11 +129,11 @@

384

If *\*buffer* points a *NULL* pointer, the function will allocate a buffer

385

of the needed size, copy the encoded data into this buffer and set

386

*\*buffer* to reference the newly allocated storage. The caller is

387

- responsible for calling :cfunc:`PyMem_Free` to free the allocated buffer

388

+ responsible for calling :c:func:`PyMem_Free` to free the allocated buffer

389

after usage.

390

391

If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),

392

- :cfunc:`PyArg_ParseTuple` will use this location as the buffer and

393

+ :c:func:`PyArg_ParseTuple` will use this location as the buffer and

394

interpret the initial value of *\*buffer_length* as the buffer size. It

395

will then copy the encoded data into the buffer and NUL-terminate it. If

396

the buffer is not large enough, a :exc:`ValueError` will be set.

397

@@ -143,71 +148,71 @@

398

399

``b`` (integer) [unsigned char]

400

Convert a nonnegative Python integer to an unsigned tiny int, stored in a C

401

- :ctype:`unsigned char`.

402

+ :c:type:`unsigned char`.

403

404

``B`` (integer) [unsigned char]

405

Convert a Python integer to a tiny int without overflow checking, stored in

406

- a C :ctype:`unsigned char`.

407

+ a C :c:type:`unsigned char`.

408

409

.. versionadded:: 2.3

410

411

``h`` (integer) [short int]

412

- Convert a Python integer to a C :ctype:`short int`.

413

+ Convert a Python integer to a C :c:type:`short int`.

414

415

``H`` (integer) [unsigned short int]

416

- Convert a Python integer to a C :ctype:`unsigned short int`, without

417

+ Convert a Python integer to a C :c:type:`unsigned short int`, without

418

overflow checking.

419

420

.. versionadded:: 2.3

421

422

``i`` (integer) [int]

423

- Convert a Python integer to a plain C :ctype:`int`.

424

+ Convert a Python integer to a plain C :c:type:`int`.

425

426

``I`` (integer) [unsigned int]

427

- Convert a Python integer to a C :ctype:`unsigned int`, without overflow

428

+ Convert a Python integer to a C :c:type:`unsigned int`, without overflow

429

checking.

430

431

.. versionadded:: 2.3

432

433

``l`` (integer) [long int]

434

- Convert a Python integer to a C :ctype:`long int`.

435

+ Convert a Python integer to a C :c:type:`long int`.

436

437

``k`` (integer) [unsigned long]

438

- Convert a Python integer or long integer to a C :ctype:`unsigned long`

439

+ Convert a Python integer or long integer to a C :c:type:`unsigned long`

440

without overflow checking.

441

442

.. versionadded:: 2.3

443

444

``L`` (integer) [PY_LONG_LONG]

445

- Convert a Python integer to a C :ctype:`long long`. This format is only

446

- available on platforms that support :ctype:`long long` (or :ctype:`_int64`

447

+ Convert a Python integer to a C :c:type:`long long`. This format is only

448

+ available on platforms that support :c:type:`long long` (or :c:type:`_int64`

449

on Windows).

450

451

``K`` (integer) [unsigned PY_LONG_LONG]

452

- Convert a Python integer or long integer to a C :ctype:`unsigned long long`

453

+ Convert a Python integer or long integer to a C :c:type:`unsigned long long`

454

without overflow checking. This format is only available on platforms that

455

- support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on

456

+ support :c:type:`unsigned long long` (or :c:type:`unsigned _int64` on

457

Windows).

458

459

.. versionadded:: 2.3

460

461

``n`` (integer) [Py_ssize_t]

462

- Convert a Python integer or long integer to a C :ctype:`Py_ssize_t`.

463

+ Convert a Python integer or long integer to a C :c:type:`Py_ssize_t`.

464

465

.. versionadded:: 2.5

466

467

``c`` (string of length 1) [char]

468

Convert a Python character, represented as a string of length 1, to a C

469

- :ctype:`char`.

470

+ :c:type:`char`.

471

472

``f`` (float) [float]

473

- Convert a Python floating point number to a C :ctype:`float`.

474

+ Convert a Python floating point number to a C :c:type:`float`.

475

476

``d`` (float) [double]

477

- Convert a Python floating point number to a C :ctype:`double`.

478

+ Convert a Python floating point number to a C :c:type:`double`.

479

480

``D`` (complex) [Py_complex]

481

- Convert a Python complex number to a C :ctype:`Py_complex` structure.

482

+ Convert a Python complex number to a C :c:type:`Py_complex` structure.

483

484

``O`` (object) [PyObject \*]

485

Store a Python object (without any conversion) in a C object pointer. The

486

@@ -217,20 +222,20 @@

487

``O!`` (object) [*typeobject*, PyObject \*]

488

Store a Python object in a C object pointer. This is similar to ``O``, but

489

takes two C arguments: the first is the address of a Python type object,

490

- the second is the address of the C variable (of type :ctype:`PyObject\*`)

491

+ the second is the address of the C variable (of type :c:type:`PyObject\*`)

492

into which the object pointer is stored. If the Python object does not

493

have the required type, :exc:`TypeError` is raised.

494

495

``O&`` (object) [*converter*, *anything*]

496

Convert a Python object to a C variable through a *converter* function.

497

This takes two arguments: the first is a function, the second is the

498

- address of a C variable (of arbitrary type), converted to :ctype:`void \*`.

499

+ address of a C variable (of arbitrary type), converted to :c:type:`void \*`.

500

The *converter* function in turn is called as follows::

501

502

status = converter(object, address);

503

504

where *object* is the Python object to be converted and *address* is the

505

- :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*`

506

+ :c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*`

507

function. The returned *status* should be ``1`` for a successful

508

conversion and ``0`` if the conversion has failed. When the conversion

509

fails, the *converter* function should raise an exception and leave the

510

@@ -239,17 +244,17 @@

511

``S`` (string) [PyStringObject \*]

512

Like ``O`` but requires that the Python object is a string object. Raises

513

:exc:`TypeError` if the object is not a string object. The C variable may

514

- also be declared as :ctype:`PyObject\*`.

515

+ also be declared as :c:type:`PyObject\*`.

516

517

``U`` (Unicode string) [PyUnicodeObject \*]

518

Like ``O`` but requires that the Python object is a Unicode object. Raises

519

:exc:`TypeError` if the object is not a Unicode object. The C variable may

520

- also be declared as :ctype:`PyObject\*`.

521

+ also be declared as :c:type:`PyObject\*`.

522

523

``t#`` (read-only character buffer) [char \*, int]

524

Like ``s#``, but accepts any object which implements the read-only buffer

525

- interface. The :ctype:`char\*` variable is set to point to the first byte

526

- of the buffer, and the :ctype:`int` is set to the length of the buffer.

527

+ interface. The :c:type:`char\*` variable is set to point to the first byte

528

+ of the buffer, and the :c:type:`int` is set to the length of the buffer.

529

Only single-segment buffer objects are accepted; :exc:`TypeError` is raised

530

for all others.

531

532

@@ -261,8 +266,8 @@

533

534

``w#`` (read-write character buffer) [char \*, Py_ssize_t]

535

Like ``s#``, but accepts any object which implements the read-write buffer

536

- interface. The :ctype:`char \*` variable is set to point to the first byte

537

- of the buffer, and the :ctype:`Py_ssize_t` is set to the length of the

538

+ interface. The :c:type:`char \*` variable is set to point to the first byte

539

+ of the buffer, and the :c:type:`Py_ssize_t` is set to the length of the

540

buffer. Only single-segment buffer objects are accepted; :exc:`TypeError`

541

is raised for all others.

542

543

@@ -297,13 +302,13 @@

544

Indicates that the remaining arguments in the Python argument list are

545

optional. The C variables corresponding to optional arguments should be

546

initialized to their default value --- when an optional argument is not

547

- specified, :cfunc:`PyArg_ParseTuple` does not touch the contents of the

548

+ specified, :c:func:`PyArg_ParseTuple` does not touch the contents of the

549

corresponding C variable(s).

550

551

``:``

552

The list of format units ends here; the string after the colon is used as

553

the function name in error messages (the "associated value" of the

554

- exception that :cfunc:`PyArg_ParseTuple` raises).

555

+ exception that :c:func:`PyArg_ParseTuple` raises).

556

557

``;``

558

The list of format units ends here; the string after the semicolon is used

559

@@ -320,40 +325,40 @@

560

should match what is specified for the corresponding format unit in that case.

561

562

For the conversion to succeed, the *arg* object must match the format and the

563

-format must be exhausted. On success, the :cfunc:`PyArg_Parse\*` functions

564

+format must be exhausted. On success, the :c:func:`PyArg_Parse\*` functions

565

return true, otherwise they return false and raise an appropriate exception.

566

-When the :cfunc:`PyArg_Parse\*` functions fail due to conversion failure in

567

+When the :c:func:`PyArg_Parse\*` functions fail due to conversion failure in

568

one of the format units, the variables at the addresses corresponding to that

569

and the following format units are left untouched.

570

571

572

-.. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)

573

+.. c:function:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)

574

575

Parse the parameters of a function that takes only positional parameters

576

into local variables. Returns true on success; on failure, it returns

577

false and raises the appropriate exception.

578

579

580

-.. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)

581

+.. c:function:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)

582

583

- Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list

584

+ Identical to :c:func:`PyArg_ParseTuple`, except that it accepts a va_list

585

rather than a variable number of arguments.

586

587

588

-.. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)

589

+.. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)

590

591

Parse the parameters of a function that takes both positional and keyword

592

parameters into local variables. Returns true on success; on failure, it

593

returns false and raises the appropriate exception.

594

595

596

-.. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)

597

+.. c:function:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)

598

599

- Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a

600

+ Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a

601

va_list rather than a variable number of arguments.

602

603

604

-.. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...)

605

+.. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...)

606

607

Function used to deconstruct the argument lists of "old-style" functions

608

--- these are functions which use the :const:`METH_OLDARGS` parameter

609

@@ -364,7 +369,7 @@

610

purpose.

611

612

613

-.. cfunction:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)

614

+.. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)

615

616

A simpler form of parameter retrieval which does not use a format string to

617

specify the types of the arguments. Functions which use this method to

618

@@ -373,7 +378,7 @@

619

should be passed as *args*; it must actually be a tuple. The length of the

620

tuple must be at least *min* and no more than *max*; *min* and *max* may be

621

equal. Additional arguments must be passed to the function, each of which

622

- should be a pointer to a :ctype:`PyObject\*` variable; these will be filled

623

+ should be a pointer to a :c:type:`PyObject\*` variable; these will be filled

624

in with the values from *args*; they will contain borrowed references. The

625

variables which correspond to optional parameters not given by *args* will

626

not be filled in; these should be initialized by the caller. This function

627

@@ -396,26 +401,26 @@

628

return result;

629

}

630

631

- The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely

632

- equivalent to this call to :cfunc:`PyArg_ParseTuple`::

633

+ The call to :c:func:`PyArg_UnpackTuple` in this example is entirely

634

+ equivalent to this call to :c:func:`PyArg_ParseTuple`::

635

636

PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

637

638

.. versionadded:: 2.2

639

640

.. versionchanged:: 2.5

641

- This function used an :ctype:`int` type for *min* and *max*. This might

642

+ This function used an :c:type:`int` type for *min* and *max*. This might

643

require changes in your code for properly supporting 64-bit systems.

644

645

646

-.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)

647

+.. c:function:: PyObject* Py_BuildValue(const char *format, ...)

648

649

Create a new value based on a format string similar to those accepted by

650

- the :cfunc:`PyArg_Parse\*` family of functions and a sequence of values.

651

+ the :c:func:`PyArg_Parse\*` family of functions and a sequence of values.

652

Returns the value or *NULL* in the case of an error; an exception will be

653

raised if *NULL* is returned.

654

655

- :cfunc:`Py_BuildValue` does not always build a tuple. It builds a tuple

656

+ :c:func:`Py_BuildValue` does not always build a tuple. It builds a tuple

657

only if its format string contains two or more format units. If the format

658

string is empty, it returns ``None``; if it contains exactly one format

659

unit, it returns whatever object is described by that format unit. To

660

@@ -425,10 +430,10 @@

661

When memory buffers are passed as parameters to supply data to build

662

objects, as for the ``s`` and ``s#`` formats, the required data is copied.

663

Buffers provided by the caller are never referenced by the objects created

664

- by :cfunc:`Py_BuildValue`. In other words, if your code invokes

665

- :cfunc:`malloc` and passes the allocated memory to :cfunc:`Py_BuildValue`,

666

- your code is responsible for calling :cfunc:`free` for that memory once

667

- :cfunc:`Py_BuildValue` returns.

668

+ by :c:func:`Py_BuildValue`. In other words, if your code invokes

669

+ :c:func:`malloc` and passes the allocated memory to :c:func:`Py_BuildValue`,

670

+ your code is responsible for calling :c:func:`free` for that memory once

671

+ :c:func:`Py_BuildValue` returns.

672

673

In the following description, the quoted form is the format unit; the entry

674

in (round) parentheses is the Python object type that the format unit will

675

@@ -464,62 +469,62 @@

676

length is ignored and ``None`` is returned.

677

678

``i`` (integer) [int]

679

- Convert a plain C :ctype:`int` to a Python integer object.

680

+ Convert a plain C :c:type:`int` to a Python integer object.

681

682

``b`` (integer) [char]

683

- Convert a plain C :ctype:`char` to a Python integer object.

684

+ Convert a plain C :c:type:`char` to a Python integer object.

685

686

``h`` (integer) [short int]

687

- Convert a plain C :ctype:`short int` to a Python integer object.

688

+ Convert a plain C :c:type:`short int` to a Python integer object.

689

690

``l`` (integer) [long int]

691

- Convert a C :ctype:`long int` to a Python integer object.

692

+ Convert a C :c:type:`long int` to a Python integer object.

693

694

``B`` (integer) [unsigned char]

695

- Convert a C :ctype:`unsigned char` to a Python integer object.

696

+ Convert a C :c:type:`unsigned char` to a Python integer object.

697

698

``H`` (integer) [unsigned short int]

699

- Convert a C :ctype:`unsigned short int` to a Python integer object.

700

+ Convert a C :c:type:`unsigned short int` to a Python integer object.

701

702

``I`` (integer/long) [unsigned int]

703

- Convert a C :ctype:`unsigned int` to a Python integer object or a Python

704

+ Convert a C :c:type:`unsigned int` to a Python integer object or a Python

705

long integer object, if it is larger than ``sys.maxint``.

706

707

``k`` (integer/long) [unsigned long]

708

- Convert a C :ctype:`unsigned long` to a Python integer object or a

709

+ Convert a C :c:type:`unsigned long` to a Python integer object or a

710

Python long integer object, if it is larger than ``sys.maxint``.

711

712

``L`` (long) [PY_LONG_LONG]

713

- Convert a C :ctype:`long long` to a Python long integer object. Only

714

- available on platforms that support :ctype:`long long`.

715

+ Convert a C :c:type:`long long` to a Python long integer object. Only

716

+ available on platforms that support :c:type:`long long`.

717

718

``K`` (long) [unsigned PY_LONG_LONG]

719

- Convert a C :ctype:`unsigned long long` to a Python long integer object.

720

- Only available on platforms that support :ctype:`unsigned long long`.

721

+ Convert a C :c:type:`unsigned long long` to a Python long integer object.

722

+ Only available on platforms that support :c:type:`unsigned long long`.

723

724

``n`` (int) [Py_ssize_t]

725

- Convert a C :ctype:`Py_ssize_t` to a Python integer or long integer.

726

+ Convert a C :c:type:`Py_ssize_t` to a Python integer or long integer.

727

728

.. versionadded:: 2.5

729

730

``c`` (string of length 1) [char]

731

- Convert a C :ctype:`int` representing a character to a Python string of

732

+ Convert a C :c:type:`int` representing a character to a Python string of

733

length 1.

734

735

``d`` (float) [double]

736

- Convert a C :ctype:`double` to a Python floating point number.

737

+ Convert a C :c:type:`double` to a Python floating point number.

738

739

``f`` (float) [float]

740

Same as ``d``.

741

742

``D`` (complex) [Py_complex \*]

743

- Convert a C :ctype:`Py_complex` structure to a Python complex number.

744

+ Convert a C :c:type:`Py_complex` structure to a Python complex number.

745

746

``O`` (object) [PyObject \*]

747

Pass a Python object untouched (except for its reference count, which is

748

incremented by one). If the object passed in is a *NULL* pointer, it is

749

assumed that this was caused because the call producing the argument

750

- found an error and set an exception. Therefore, :cfunc:`Py_BuildValue`

751

+ found an error and set an exception. Therefore, :c:func:`Py_BuildValue`

752

will return *NULL* but won't raise an exception. If no exception has

753

been raised yet, :exc:`SystemError` is set.

754

755

@@ -534,7 +539,7 @@

756

``O&`` (object) [*converter*, *anything*]

757

Convert *anything* to a Python object through a *converter* function.

758

The function is called with *anything* (which should be compatible with

759

- :ctype:`void \*`) as its argument and should return a "new" Python

760

+ :c:type:`void \*`) as its argument and should return a "new" Python

761

object, or *NULL* if an error occurred.

762

763

``(items)`` (tuple) [*matching-items*]

764

@@ -553,7 +558,7 @@

765

If there is an error in the format string, the :exc:`SystemError` exception

766

is set and *NULL* returned.

767

768

-.. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)

769

+.. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)

770

771

- Identical to :cfunc:`Py_BuildValue`, except that it accepts a va_list

772

+ Identical to :c:func:`Py_BuildValue`, except that it accepts a va_list

773

rather than a variable number of arguments.

774

diff -r 8527427914a2 Doc/c-api/bool.rst

775

--- a/Doc/c-api/bool.rst

776

+++ b/Doc/c-api/bool.rst

777

@@ -11,26 +11,26 @@

778

are available, however.

779

780

781

-.. cfunction:: int PyBool_Check(PyObject *o)

782

+.. c:function:: int PyBool_Check(PyObject *o)

783

784

- Return true if *o* is of type :cdata:`PyBool_Type`.

785

+ Return true if *o* is of type :c:data:`PyBool_Type`.

786

787

.. versionadded:: 2.3

788

789

790

-.. cvar:: PyObject* Py_False

791

+.. c:var:: PyObject* Py_False

792

793

The Python ``False`` object. This object has no methods. It needs to be

794

treated just like any other object with respect to reference counts.

795

796

797

-.. cvar:: PyObject* Py_True

798

+.. c:var:: PyObject* Py_True

799

800

The Python ``True`` object. This object has no methods. It needs to be treated

801

just like any other object with respect to reference counts.

802

803

804

-.. cmacro:: Py_RETURN_FALSE

805

+.. c:macro:: Py_RETURN_FALSE

806

807

Return :const:`Py_False` from a function, properly incrementing its reference

808

count.

809

@@ -38,7 +38,7 @@

810

.. versionadded:: 2.4

811

812

813

-.. cmacro:: Py_RETURN_TRUE

814

+.. c:macro:: Py_RETURN_TRUE

815

816

Return :const:`Py_True` from a function, properly incrementing its reference

817

count.

818

@@ -46,7 +46,7 @@

819

.. versionadded:: 2.4

820

821

822

-.. cfunction:: PyObject* PyBool_FromLong(long v)

823

+.. c:function:: PyObject* PyBool_FromLong(long v)

824

825

Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the

826

truth value of *v*.

827

diff -r 8527427914a2 Doc/c-api/buffer.rst

828

--- a/Doc/c-api/buffer.rst

829

+++ b/Doc/c-api/buffer.rst

830

@@ -27,7 +27,7 @@

831

An example user of the buffer interface is the file object's :meth:`write`

832

method. Any object that can export a series of bytes through the buffer

833

interface can be written to a file. There are a number of format codes to

834

-:cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface,

835

+:c:func:`PyArg_ParseTuple` that operate against an object's buffer interface,

836

returning data from the target object.

837

838

Starting from version 1.6, Python has been providing Python-level buffer

839

@@ -47,49 +47,49 @@

840

==============================

841

842

843

-.. ctype:: Py_buffer

844

+.. c:type:: Py_buffer

845

846

- .. cmember:: void *buf

847

+ .. c:member:: void *buf

848

849

A pointer to the start of the memory for the object.

850

851

- .. cmember:: Py_ssize_t len

852

+ .. c:member:: Py_ssize_t len

853

:noindex:

854

855

The total length of the memory in bytes.

856

857

- .. cmember:: int readonly

858

+ .. c:member:: int readonly

859

860

An indicator of whether the buffer is read only.

861

862

- .. cmember:: const char *format

863

+ .. c:member:: const char *format

864

:noindex:

865

866

A *NULL* terminated string in :mod:`struct` module style syntax giving

867

the contents of the elements available through the buffer. If this is

868

*NULL*, ``"B"`` (unsigned bytes) is assumed.

869

870

- .. cmember:: int ndim

871

+ .. c:member:: int ndim

872

873

The number of dimensions the memory represents as a multi-dimensional

874

- array. If it is 0, :cdata:`strides` and :cdata:`suboffsets` must be

875

+ array. If it is 0, :c:data:`strides` and :c:data:`suboffsets` must be

876

*NULL*.

877

878

- .. cmember:: Py_ssize_t *shape

879

+ .. c:member:: Py_ssize_t *shape

880

881

- An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the

882

+ An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the

883

shape of the memory as a multi-dimensional array. Note that

884

``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to

885

- :cdata:`len`.

886

+ :c:data:`len`.

887

888

- .. cmember:: Py_ssize_t *strides

889

+ .. c:member:: Py_ssize_t *strides

890

891

- An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the

892

+ An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the

893

number of bytes to skip to get to a new element in each dimension.

894

895

- .. cmember:: Py_ssize_t *suboffsets

896

+ .. c:member:: Py_ssize_t *suboffsets

897

898

- An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim`. If these

899

+ An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim`. If these

900

suboffset numbers are greater than or equal to 0, then the value stored

901

along the indicated dimension is a pointer and the suboffset value

902

dictates how many bytes to add to the pointer after de-referencing. A

903

@@ -114,16 +114,16 @@

904

}

905

906

907

- .. cmember:: Py_ssize_t itemsize

908

+ .. c:member:: Py_ssize_t itemsize

909

910

This is a storage for the itemsize (in bytes) of each element of the

911

shared memory. It is technically un-necessary as it can be obtained

912

- using :cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know

913

+ using :c:func:`PyBuffer_SizeFromFormat`, however an exporter may know

914

this information without parsing the format string and it is necessary

915

to know the itemsize for proper interpretation of striding. Therefore,

916

storing it is more convenient and faster.

917

918

- .. cmember:: void *internal

919

+ .. c:member:: void *internal

920

921

This is for use internally by the exporting object. For example, this

922

might be re-cast as an integer by the exporter and used to store flags

923

@@ -136,14 +136,14 @@

924

========================

925

926

927

-.. cfunction:: int PyObject_CheckBuffer(PyObject *obj)

928

+.. c:function:: int PyObject_CheckBuffer(PyObject *obj)

929

930

Return 1 if *obj* supports the buffer interface otherwise 0.

931

932

933

-.. cfunction:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)

934

+.. c:function:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)

935

936

- Export *obj* into a :ctype:`Py_buffer`, *view*. These arguments must

937

+ Export *obj* into a :c:type:`Py_buffer`, *view*. These arguments must

938

never be *NULL*. The *flags* argument is a bit field indicating what

939

kind of buffer the caller is prepared to deal with and therefore what

940

kind of buffer the exporter is allowed to return. The buffer interface

941

@@ -156,131 +156,131 @@

942

just not possible. These errors should be a :exc:`BufferError` unless

943

there is another error that is actually causing the problem. The

944

exporter can use flags information to simplify how much of the

945

- :cdata:`Py_buffer` structure is filled in with non-default values and/or

946

+ :c:data:`Py_buffer` structure is filled in with non-default values and/or

947

raise an error if the object can't support a simpler view of its memory.

948

949

0 is returned on success and -1 on error.

950

951

The following table gives possible values to the *flags* arguments.

952

953

- +------------------------------+---------------------------------------------------+

954

- | Flag | Description |

955

- +==============================+===================================================+

956

- | :cmacro:`PyBUF_SIMPLE` | This is the default flag state. The returned |

957

- | | buffer may or may not have writable memory. The |

958

- | | format of the data will be assumed to be unsigned |

959

- | | bytes. This is a "stand-alone" flag constant. It |

960

- | | never needs to be '|'d to the others. The exporter|

961

- | | will raise an error if it cannot provide such a |

962

- | | contiguous buffer of bytes. |

963

- | | |

964

- +------------------------------+---------------------------------------------------+

965

- | :cmacro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is |

966

- | | not writable, then raise an error. |

967

- +------------------------------+---------------------------------------------------+

968

- | :cmacro:`PyBUF_STRIDES` | This implies :cmacro:`PyBUF_ND`. The returned |

969

- | | buffer must provide strides information (i.e. the |

970

- | | strides cannot be NULL). This would be used when |

971

- | | the consumer can handle strided, discontiguous |

972

- | | arrays. Handling strides automatically assumes |

973

- | | you can handle shape. The exporter can raise an |

974

- | | error if a strided representation of the data is |

975

- | | not possible (i.e. without the suboffsets). |

976

- | | |

977

- +------------------------------+---------------------------------------------------+

978

- | :cmacro:`PyBUF_ND` | The returned buffer must provide shape |

979

- | | information. The memory will be assumed C-style |

980

- | | contiguous (last dimension varies the |

981

- | | fastest). The exporter may raise an error if it |

982

- | | cannot provide this kind of contiguous buffer. If |

983

- | | this is not given then shape will be *NULL*. |

984

- | | |

985

- | | |

986

- | | |

987

- +------------------------------+---------------------------------------------------+

988

- |:cmacro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned |

989

- |:cmacro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last |

990

- |:cmacro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous |

991

- | | (first dimension varies the fastest) or either |

992

- | | one. All of these flags imply |

993

- | | :cmacro:`PyBUF_STRIDES` and guarantee that the |

994

- | | strides buffer info structure will be filled in |

995

- | | correctly. |

996

- | | |

997

- +------------------------------+---------------------------------------------------+

998

- | :cmacro:`PyBUF_INDIRECT` | This flag indicates the returned buffer must have |

999

- | | suboffsets information (which can be NULL if no |

1000

- | | suboffsets are needed). This can be used when |

1001

- | | the consumer can handle indirect array |

1002

- | | referencing implied by these suboffsets. This |

1003

- | | implies :cmacro:`PyBUF_STRIDES`. |

1004

- | | |

1005

- | | |

1006

- | | |

1007

- +------------------------------+---------------------------------------------------+

1008

- | :cmacro:`PyBUF_FORMAT` | The returned buffer must have true format |

1009

- | | information if this flag is provided. This would |

1010

- | | be used when the consumer is going to be checking |

1011

- | | for what 'kind' of data is actually stored. An |

1012

- | | exporter should always be able to provide this |

1013

- | | information if requested. If format is not |

1014

- | | explicitly requested then the format must be |

1015

- | | returned as *NULL* (which means ``'B'``, or |

1016

- | | unsigned bytes) |

1017

- +------------------------------+---------------------------------------------------+

1018

- | :cmacro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | |

1019

- | | PyBUF_WRITABLE)``. |

1020

- +------------------------------+---------------------------------------------------+

1021

- | :cmacro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. |

1022

- | | |

1023

- +------------------------------+---------------------------------------------------+

1024

- | :cmacro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | |

1025

- | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |

1026

- +------------------------------+---------------------------------------------------+

1027

- | :cmacro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | |

1028

- | | PyBUF_FORMAT)``. |

1029

- +------------------------------+---------------------------------------------------+

1030

- | :cmacro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | |

1031

- | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |

1032

- +------------------------------+---------------------------------------------------+

1033

- | :cmacro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | |

1034

- | | PyBUF_FORMAT)``. |

1035

- +------------------------------+---------------------------------------------------+

1036

- | :cmacro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | |

1037

- | | PyBUF_WRITABLE)``. |

1038

- +------------------------------+---------------------------------------------------+

1039

- | :cmacro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. |

1040

- | | |

1041

- +------------------------------+---------------------------------------------------+

1042

+ +-------------------------------+---------------------------------------------------+

1043

+ | Flag | Description |

1044

+ +===============================+===================================================+

1045

+ | :c:macro:`PyBUF_SIMPLE` | This is the default flag state. The returned |

1046

+ | | buffer may or may not have writable memory. The |

1047

+ | | format of the data will be assumed to be unsigned |

1048

+ | | bytes. This is a "stand-alone" flag constant. It |

1049

+ | | never needs to be '|'d to the others. The exporter|

1050

+ | | will raise an error if it cannot provide such a |

1051

+ | | contiguous buffer of bytes. |

1052

+ | | |

1053

+ +-------------------------------+---------------------------------------------------+

1054

+ | :c:macro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is |

1055

+ | | not writable, then raise an error. |

1056

+ +-------------------------------+---------------------------------------------------+

1057

+ | :c:macro:`PyBUF_STRIDES` | This implies :c:macro:`PyBUF_ND`. The returned |

1058

+ | | buffer must provide strides information (i.e. the |

1059

+ | | strides cannot be NULL). This would be used when |

1060

+ | | the consumer can handle strided, discontiguous |

1061

+ | | arrays. Handling strides automatically assumes |

1062

+ | | you can handle shape. The exporter can raise an |

1063

+ | | error if a strided representation of the data is |

1064

+ | | not possible (i.e. without the suboffsets). |

1065

+ | | |

1066

+ +-------------------------------+---------------------------------------------------+

1067

+ | :c:macro:`PyBUF_ND` | The returned buffer must provide shape |

1068

+ | | information. The memory will be assumed C-style |

1069

+ | | contiguous (last dimension varies the |

1070

+ | | fastest). The exporter may raise an error if it |

1071

+ | | cannot provide this kind of contiguous buffer. If |

1072

+ | | this is not given then shape will be *NULL*. |

1073

+ | | |

1074

+ | | |

1075

+ | | |

1076

+ +-------------------------------+---------------------------------------------------+

1077

+ |:c:macro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned |

1078

+ |:c:macro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last |

1079

+ |:c:macro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous |

1080

+ | | (first dimension varies the fastest) or either |

1081

+ | | one. All of these flags imply |

1082

+ | | :c:macro:`PyBUF_STRIDES` and guarantee that the |

1083

+ | | strides buffer info structure will be filled in |

1084

+ | | correctly. |

1085

+ | | |

1086

+ +-------------------------------+---------------------------------------------------+

1087

+ | :c:macro:`PyBUF_INDIRECT` | This flag indicates the returned buffer must have |

1088

+ | | suboffsets information (which can be NULL if no |

1089

+ | | suboffsets are needed). This can be used when |

1090

+ | | the consumer can handle indirect array |

1091

+ | | referencing implied by these suboffsets. This |

1092

+ | | implies :c:macro:`PyBUF_STRIDES`. |

1093

+ | | |

1094

+ | | |

1095

+ | | |

1096

+ +-------------------------------+---------------------------------------------------+

1097

+ | :c:macro:`PyBUF_FORMAT` | The returned buffer must have true format |

1098

+ | | information if this flag is provided. This would |

1099

+ | | be used when the consumer is going to be checking |

1100

+ | | for what 'kind' of data is actually stored. An |

1101

+ | | exporter should always be able to provide this |

1102

+ | | information if requested. If format is not |

1103

+ | | explicitly requested then the format must be |

1104

+ | | returned as *NULL* (which means ``'B'``, or |

1105

+ | | unsigned bytes) |

1106

+ +-------------------------------+---------------------------------------------------+

1107

+ | :c:macro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | |

1108

+ | | PyBUF_WRITABLE)``. |

1109

+ +-------------------------------+---------------------------------------------------+

1110

+ | :c:macro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. |

1111

+ | | |

1112

+ +-------------------------------+---------------------------------------------------+

1113

+ | :c:macro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | |

1114

+ | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |

1115

+ +-------------------------------+---------------------------------------------------+

1116

+ | :c:macro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | |

1117

+ | | PyBUF_FORMAT)``. |

1118

+ +-------------------------------+---------------------------------------------------+

1119

+ | :c:macro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | |

1120

+ | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |

1121

+ +-------------------------------+---------------------------------------------------+

1122

+ | :c:macro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | |

1123

+ | | PyBUF_FORMAT)``. |

1124

+ +-------------------------------+---------------------------------------------------+

1125

+ | :c:macro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | |

1126

+ | | PyBUF_WRITABLE)``. |

1127

+ +-------------------------------+---------------------------------------------------+

1128

+ | :c:macro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. |

1129

+ | | |

1130

+ +-------------------------------+---------------------------------------------------+

1131

1132

1133

-.. cfunction:: void PyBuffer_Release(Py_buffer *view)

1134

+.. c:function:: void PyBuffer_Release(Py_buffer *view)

1135

1136

Release the buffer *view*. This should be called when the buffer

1137

is no longer being used as it may free memory from it.

1138

1139

1140

-.. cfunction:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)

1141

+.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)

1142

1143

- Return the implied :cdata:`~Py_buffer.itemsize` from the struct-stype

1144

- :cdata:`~Py_buffer.format`.

1145

+ Return the implied :c:data:`~Py_buffer.itemsize` from the struct-stype

1146

+ :c:data:`~Py_buffer.format`.

1147

1148

1149

-.. cfunction:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)

1150

+.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)

1151

1152

Return 1 if the memory defined by the *view* is C-style (*fortran* is

1153

``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one

1154

(*fortran* is ``'A'``). Return 0 otherwise.

1155

1156

1157

-.. cfunction:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char fortran)

1158

+.. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char fortran)

1159

1160

Fill the *strides* array with byte-strides of a contiguous (C-style if

1161

*fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'``) array of the

1162

given shape with the given number of bytes per element.

1163

1164

1165

-.. cfunction:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags)

1166

+.. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags)

1167

1168

Fill in a buffer-info structure, *view*, correctly for an exporter that can

1169

only share a contiguous chunk of memory of "unsigned bytes" of the given

1170

@@ -295,13 +295,13 @@

1171

A :class:`memoryview` object exposes the new C level buffer interface as a

1172

Python object which can then be passed around like any other object.

1173

1174

-.. cfunction:: PyObject *PyMemoryView_FromObject(PyObject *obj)

1175

+.. c:function:: PyObject *PyMemoryView_FromObject(PyObject *obj)

1176

1177

Create a memoryview object from an object that defines the new buffer

1178

interface.

1179

1180

1181

-.. cfunction:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)

1182

+.. c:function:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)

1183

1184

Create a memoryview object wrapping the given buffer-info structure *view*.

1185

The memoryview object then owns the buffer, which means you shouldn't

1186

@@ -309,7 +309,7 @@

1187

memoryview object.

1188

1189

1190

-.. cfunction:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)

1191

+.. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)

1192

1193

Create a memoryview object to a contiguous chunk of memory (in either

1194

'C' or 'F'ortran *order*) from an object that defines the buffer

1195

@@ -318,13 +318,13 @@

1196

new bytes object.

1197

1198

1199

-.. cfunction:: int PyMemoryView_Check(PyObject *obj)

1200

+.. c:function:: int PyMemoryView_Check(PyObject *obj)

1201

1202

Return true if the object *obj* is a memoryview object. It is not

1203

currently allowed to create subclasses of :class:`memoryview`.

1204

1205

1206

-.. cfunction:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *obj)

1207

+.. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *obj)

1208

1209

Return a pointer to the buffer-info structure wrapped by the given

1210

object. The object **must** be a memoryview instance; this macro doesn't

1211

@@ -337,7 +337,7 @@

1212

.. index:: single: PyBufferProcs

1213

1214

More information on the old buffer interface is provided in the section

1215

-:ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.

1216

+:ref:`buffer-structs`, under the description for :c:type:`PyBufferProcs`.

1217

1218

A "buffer object" is defined in the :file:`bufferobject.h` header (included by

1219

:file:`Python.h`). These objects look very similar to string objects at the

1220

@@ -356,36 +356,36 @@

1221

native, in-memory format.

1222

1223

1224

-.. ctype:: PyBufferObject

1225

+.. c:type:: PyBufferObject

1226

1227

- This subtype of :ctype:`PyObject` represents a buffer object.

1228

+ This subtype of :c:type:`PyObject` represents a buffer object.

1229

1230

1231

-.. cvar:: PyTypeObject PyBuffer_Type

1232

+.. c:var:: PyTypeObject PyBuffer_Type

1233

1234

.. index:: single: BufferType (in module types)

1235

1236

- The instance of :ctype:`PyTypeObject` which represents the Python buffer type;

1237

+ The instance of :c:type:`PyTypeObject` which represents the Python buffer type;

1238

it is the same object as ``buffer`` and ``types.BufferType`` in the Python

1239

layer. .

1240

1241

1242

-.. cvar:: int Py_END_OF_BUFFER

1243

+.. c:var:: int Py_END_OF_BUFFER

1244

1245

This constant may be passed as the *size* parameter to

1246

- :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It

1247

- indicates that the new :ctype:`PyBufferObject` should refer to *base*

1248

+ :c:func:`PyBuffer_FromObject` or :c:func:`PyBuffer_FromReadWriteObject`. It

1249

+ indicates that the new :c:type:`PyBufferObject` should refer to *base*

1250

object from the specified *offset* to the end of its exported buffer.

1251

Using this enables the caller to avoid querying the *base* object for its

1252

length.

1253

1254

1255

-.. cfunction:: int PyBuffer_Check(PyObject *p)

1256

+.. c:function:: int PyBuffer_Check(PyObject *p)

1257

1258

- Return true if the argument has type :cdata:`PyBuffer_Type`.

1259

+ Return true if the argument has type :c:data:`PyBuffer_Type`.

1260

1261

1262

-.. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)

1263

+.. c:function:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)

1264

1265

Return a new read-only buffer object. This raises :exc:`TypeError` if

1266

*base* doesn't support the read-only buffer protocol or doesn't provide

1267

@@ -397,24 +397,24 @@

1268

length of the *base* object's exported buffer data.

1269

1270

.. versionchanged:: 2.5

1271

- This function used an :ctype:`int` type for *offset* and *size*. This

1272

+ This function used an :c:type:`int` type for *offset* and *size*. This

1273

might require changes in your code for properly supporting 64-bit

1274

systems.

1275

1276

1277

-.. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)

1278

+.. c:function:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)

1279

1280

Return a new writable buffer object. Parameters and exceptions are similar

1281

- to those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not

1282

+ to those for :c:func:`PyBuffer_FromObject`. If the *base* object does not

1283

export the writeable buffer protocol, then :exc:`TypeError` is raised.

1284

1285

.. versionchanged:: 2.5

1286

- This function used an :ctype:`int` type for *offset* and *size*. This

1287

+ This function used an :c:type:`int` type for *offset* and *size*. This

1288

might require changes in your code for properly supporting 64-bit

1289

systems.

1290

1291

1292

-.. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)

1293

+.. c:function:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)

1294

1295

Return a new read-only buffer object that reads from a specified location

1296

in memory, with a specified size. The caller is responsible for ensuring

1297

@@ -424,27 +424,27 @@

1298

*size* parameter; :exc:`ValueError` will be raised in that case.

1299

1300

.. versionchanged:: 2.5

1301

- This function used an :ctype:`int` type for *size*. This might require

1302

+ This function used an :c:type:`int` type for *size*. This might require

1303

changes in your code for properly supporting 64-bit systems.

1304

1305

1306

-.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)

1307

+.. c:function:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)

1308

1309

- Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is

1310

+ Similar to :c:func:`PyBuffer_FromMemory`, but the returned buffer is

1311

writable.

1312

1313

.. versionchanged:: 2.5

1314

- This function used an :ctype:`int` type for *size*. This might require

1315

+ This function used an :c:type:`int` type for *size*. This might require

1316

changes in your code for properly supporting 64-bit systems.

1317

1318

1319

-.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)

1320

+.. c:function:: PyObject* PyBuffer_New(Py_ssize_t size)

1321

1322

Return a new writable buffer object that maintains its own memory buffer of

1323

*size* bytes. :exc:`ValueError` is returned if *size* is not zero or

1324

positive. Note that the memory buffer (as returned by

1325

- :cfunc:`PyObject_AsWriteBuffer`) is not specifically aligned.

1326

+ :c:func:`PyObject_AsWriteBuffer`) is not specifically aligned.

1327

1328

.. versionchanged:: 2.5

1329

- This function used an :ctype:`int` type for *size*. This might require

1330

+ This function used an :c:type:`int` type for *size*. This might require

1331

changes in your code for properly supporting 64-bit systems.

1332

diff -r 8527427914a2 Doc/c-api/bytearray.rst

1333

--- a/Doc/c-api/bytearray.rst

1334

+++ b/Doc/c-api/bytearray.rst

1335

@@ -10,26 +10,26 @@

1336

.. versionadded:: 2.6

1337

1338

1339

-.. ctype:: PyByteArrayObject

1340

+.. c:type:: PyByteArrayObject

1341

1342

- This subtype of :ctype:`PyObject` represents a Python bytearray object.

1343

+ This subtype of :c:type:`PyObject` represents a Python bytearray object.

1344

1345

1346

-.. cvar:: PyTypeObject PyByteArray_Type

1347

+.. c:var:: PyTypeObject PyByteArray_Type

1348

1349

- This instance of :ctype:`PyTypeObject` represents the Python bytearray type;

1350

+ This instance of :c:type:`PyTypeObject` represents the Python bytearray type;

1351

it is the same object as ``bytearray`` in the Python layer.

1352

1353

Type check macros

1354

^^^^^^^^^^^^^^^^^

1355

1356

-.. cfunction:: int PyByteArray_Check(PyObject *o)

1357

+.. c:function:: int PyByteArray_Check(PyObject *o)

1358

1359

Return true if the object *o* is a bytearray object or an instance of a

1360

subtype of the bytearray type.

1361

1362

1363

-.. cfunction:: int PyByteArray_CheckExact(PyObject *o)

1364

+.. c:function:: int PyByteArray_CheckExact(PyObject *o)

1365

1366

Return true if the object *o* is a bytearray object, but not an instance of a

1367

subtype of the bytearray type.

1368

@@ -38,7 +38,7 @@

1369

Direct API functions

1370

^^^^^^^^^^^^^^^^^^^^

1371

1372

-.. cfunction:: PyObject* PyByteArray_FromObject(PyObject *o)

1373

+.. c:function:: PyObject* PyByteArray_FromObject(PyObject *o)

1374

1375

Return a new bytearray object from any object, *o*, that implements the

1376

buffer protocol.

1377

@@ -46,29 +46,29 @@

1378

.. XXX expand about the buffer protocol, at least somewhere

1379

1380

1381

-.. cfunction:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)

1382

+.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)

1383

1384

Create a new bytearray object from *string* and its length, *len*. On

1385

failure, *NULL* is returned.

1386

1387

1388

-.. cfunction:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)

1389

+.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)

1390

1391

Concat bytearrays *a* and *b* and return a new bytearray with the result.

1392

1393

1394

-.. cfunction:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)

1395

+.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)

1396

1397

Return the size of *bytearray* after checking for a *NULL* pointer.

1398

1399

1400

-.. cfunction:: char* PyByteArray_AsString(PyObject *bytearray)

1401

+.. c:function:: char* PyByteArray_AsString(PyObject *bytearray)

1402

1403

Return the contents of *bytearray* as a char array after checking for a

1404

*NULL* pointer.

1405

1406

1407

-.. cfunction:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)

1408

+.. c:function:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)

1409

1410

Resize the internal buffer of *bytearray* to *len*.

1411

1412

@@ -77,11 +77,11 @@

1413

1414

These macros trade safety for speed and they don't check pointers.

1415

1416

-.. cfunction:: char* PyByteArray_AS_STRING(PyObject *bytearray)

1417

+.. c:function:: char* PyByteArray_AS_STRING(PyObject *bytearray)

1418

1419

- Macro version of :cfunc:`PyByteArray_AsString`.

1420

+ Macro version of :c:func:`PyByteArray_AsString`.

1421

1422

1423

-.. cfunction:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)

1424

+.. c:function:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)

1425

1426

- Macro version of :cfunc:`PyByteArray_Size`.

1427

+ Macro version of :c:func:`PyByteArray_Size`.

1428

diff -r 8527427914a2 Doc/c-api/capsule.rst

1429

--- a/Doc/c-api/capsule.rst

1430

+++ b/Doc/c-api/capsule.rst

1431

@@ -10,33 +10,33 @@

1432

Refer to :ref:`using-capsules` for more information on using these objects.

1433

1434

1435

-.. ctype:: PyCapsule

1436

+.. c:type:: PyCapsule

1437

1438

- This subtype of :ctype:`PyObject` represents an opaque value, useful for C

1439

- extension modules who need to pass an opaque value (as a :ctype:`void\*`

1440

+ This subtype of :c:type:`PyObject` represents an opaque value, useful for C

1441

+ extension modules who need to pass an opaque value (as a :c:type:`void\*`

1442

pointer) through Python code to other C code. It is often used to make a C

1443

function pointer defined in one module available to other modules, so the

1444

regular import mechanism can be used to access C APIs defined in dynamically

1445

loaded modules.

1446

1447

-.. ctype:: PyCapsule_Destructor

1448

+.. c:type:: PyCapsule_Destructor

1449

1450

The type of a destructor callback for a capsule. Defined as::

1451

1452

typedef void (*PyCapsule_Destructor)(PyObject *);

1453

1454

- See :cfunc:`PyCapsule_New` for the semantics of PyCapsule_Destructor

1455

+ See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor

1456

callbacks.

1457

1458

1459

-.. cfunction:: int PyCapsule_CheckExact(PyObject *p)

1460

+.. c:function:: int PyCapsule_CheckExact(PyObject *p)

1461

1462

- Return true if its argument is a :ctype:`PyCapsule`.

1463

+ Return true if its argument is a :c:type:`PyCapsule`.

1464

1465

1466

-.. cfunction:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

1467

+.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

1468

1469

- Create a :ctype:`PyCapsule` encapsulating the *pointer*. The *pointer*

1470

+ Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer*

1471

argument may not be *NULL*.

1472

1473

On failure, set an exception and return *NULL*.

1474

@@ -50,91 +50,91 @@

1475

1476

If this capsule will be stored as an attribute of a module, the *name* should

1477

be specified as ``modulename.attributename``. This will enable other modules

1478

- to import the capsule using :cfunc:`PyCapsule_Import`.

1479

+ to import the capsule using :c:func:`PyCapsule_Import`.

1480

1481

1482

-.. cfunction:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)

1483

+.. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)

1484

1485

Retrieve the *pointer* stored in the capsule. On failure, set an exception

1486

and return *NULL*.

1487

1488

The *name* parameter must compare exactly to the name stored in the capsule.

1489

If the name stored in the capsule is *NULL*, the *name* passed in must also

1490

- be *NULL*. Python uses the C function :cfunc:`strcmp` to compare capsule

1491

+ be *NULL*. Python uses the C function :c:func:`strcmp` to compare capsule

1492

names.

1493

1494

1495

-.. cfunction:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

1496

+.. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

1497

1498

Return the current destructor stored in the capsule. On failure, set an

1499

exception and return *NULL*.

1500

1501

It is legal for a capsule to have a *NULL* destructor. This makes a *NULL*

1502

- return code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or

1503

- :cfunc:`PyErr_Occurred` to disambiguate.

1504

+ return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or

1505

+ :c:func:`PyErr_Occurred` to disambiguate.

1506

1507

1508

-.. cfunction:: void* PyCapsule_GetContext(PyObject *capsule)

1509

+.. c:function:: void* PyCapsule_GetContext(PyObject *capsule)

1510

1511

Return the current context stored in the capsule. On failure, set an

1512

exception and return *NULL*.

1513

1514

It is legal for a capsule to have a *NULL* context. This makes a *NULL*

1515

- return code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or

1516

- :cfunc:`PyErr_Occurred` to disambiguate.

1517

+ return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or

1518

+ :c:func:`PyErr_Occurred` to disambiguate.

1519

1520

1521

-.. cfunction:: const char* PyCapsule_GetName(PyObject *capsule)

1522

+.. c:function:: const char* PyCapsule_GetName(PyObject *capsule)

1523

1524

Return the current name stored in the capsule. On failure, set an exception

1525

and return *NULL*.

1526

1527

It is legal for a capsule to have a *NULL* name. This makes a *NULL* return

1528

- code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or

1529

- :cfunc:`PyErr_Occurred` to disambiguate.

1530

+ code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or

1531

+ :c:func:`PyErr_Occurred` to disambiguate.

1532

1533

1534

-.. cfunction:: void* PyCapsule_Import(const char *name, int no_block)

1535

+.. c:function:: void* PyCapsule_Import(const char *name, int no_block)

1536

1537

Import a pointer to a C object from a capsule attribute in a module. The

1538

*name* parameter should specify the full name to the attribute, as in

1539

``module.attribute``. The *name* stored in the capsule must match this

1540

string exactly. If *no_block* is true, import the module without blocking

1541

- (using :cfunc:`PyImport_ImportModuleNoBlock`). If *no_block* is false,

1542

- import the module conventionally (using :cfunc:`PyImport_ImportModule`).

1543

+ (using :c:func:`PyImport_ImportModuleNoBlock`). If *no_block* is false,

1544

+ import the module conventionally (using :c:func:`PyImport_ImportModule`).

1545

1546

Return the capsule's internal *pointer* on success. On failure, set an

1547

- exception and return *NULL*. However, if :cfunc:`PyCapsule_Import` failed to

1548

+ exception and return *NULL*. However, if :c:func:`PyCapsule_Import` failed to

1549

import the module, and *no_block* was true, no exception is set.

1550

1551

-.. cfunction:: int PyCapsule_IsValid(PyObject *capsule, const char *name)

1552

+.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name)

1553

1554

Determines whether or not *capsule* is a valid capsule. A valid capsule is

1555

- non-*NULL*, passes :cfunc:`PyCapsule_CheckExact`, has a non-*NULL* pointer

1556

+ non-*NULL*, passes :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer

1557

stored in it, and its internal name matches the *name* parameter. (See

1558

- :cfunc:`PyCapsule_GetPointer` for information on how capsule names are

1559

+ :c:func:`PyCapsule_GetPointer` for information on how capsule names are

1560

compared.)

1561

1562

- In other words, if :cfunc:`PyCapsule_IsValid` returns a true value, calls to

1563

- any of the accessors (any function starting with :cfunc:`PyCapsule_Get`) are

1564

+ In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to

1565

+ any of the accessors (any function starting with :c:func:`PyCapsule_Get`) are

1566

guaranteed to succeed.

1567

1568

Return a nonzero value if the object is valid and matches the name passed in.

1569

Return 0 otherwise. This function will not fail.

1570

1571

-.. cfunction:: int PyCapsule_SetContext(PyObject *capsule, void *context)

1572

+.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)

1573

1574

Set the context pointer inside *capsule* to *context*.

1575

1576

Return 0 on success. Return nonzero and set an exception on failure.

1577

1578

-.. cfunction:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

1579

+.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

1580

1581

Set the destructor inside *capsule* to *destructor*.

1582

1583

Return 0 on success. Return nonzero and set an exception on failure.

1584

1585

-.. cfunction:: int PyCapsule_SetName(PyObject *capsule, const char *name)

1586

+.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)

1587

1588

Set the name inside *capsule* to *name*. If non-*NULL*, the name must

1589

outlive the capsule. If the previous *name* stored in the capsule was not

1590

@@ -142,7 +142,7 @@

1591

1592

Return 0 on success. Return nonzero and set an exception on failure.

1593

1594

-.. cfunction:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

1595

+.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

1596

1597

Set the void pointer inside *capsule* to *pointer*. The pointer may not be

1598

*NULL*.

1599

diff -r 8527427914a2 Doc/c-api/cell.rst

1600

--- a/Doc/c-api/cell.rst

1601

+++ b/Doc/c-api/cell.rst

1602

@@ -15,39 +15,39 @@

1603

Cell objects are not likely to be useful elsewhere.

1604

1605

1606

-.. ctype:: PyCellObject

1607

+.. c:type:: PyCellObject

1608

1609

The C structure used for cell objects.

1610

1611

1612

-.. cvar:: PyTypeObject PyCell_Type

1613

+.. c:var:: PyTypeObject PyCell_Type

1614

1615

The type object corresponding to cell objects.

1616

1617

1618

-.. cfunction:: int PyCell_Check(ob)

1619

+.. c:function:: int PyCell_Check(ob)

1620

1621

Return true if *ob* is a cell object; *ob* must not be *NULL*.

1622

1623

1624

-.. cfunction:: PyObject* PyCell_New(PyObject *ob)

1625

+.. c:function:: PyObject* PyCell_New(PyObject *ob)

1626

1627

Create and return a new cell object containing the value *ob*. The parameter may

1628

be *NULL*.

1629

1630

1631

-.. cfunction:: PyObject* PyCell_Get(PyObject *cell)

1632

+.. c:function:: PyObject* PyCell_Get(PyObject *cell)

1633

1634

Return the contents of the cell *cell*.

1635

1636

1637

-.. cfunction:: PyObject* PyCell_GET(PyObject *cell)

1638

+.. c:function:: PyObject* PyCell_GET(PyObject *cell)

1639

1640

Return the contents of the cell *cell*, but without checking that *cell* is

1641

non-*NULL* and a cell object.

1642

1643

1644

-.. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value)

1645

+.. c:function:: int PyCell_Set(PyObject *cell, PyObject *value)

1646

1647

Set the contents of the cell object *cell* to *value*. This releases the

1648

reference to any current content of the cell. *value* may be *NULL*. *cell*

1649

@@ -55,7 +55,7 @@

1650

success, ``0`` will be returned.

1651

1652

1653

-.. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value)

1654

+.. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)

1655

1656

Sets the value of the cell object *cell* to *value*. No reference counts are

1657

adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must

1658

diff -r 8527427914a2 Doc/c-api/class.rst

1659

--- a/Doc/c-api/class.rst

1660

+++ b/Doc/c-api/class.rst

1661

@@ -12,12 +12,12 @@

1662

will want to work with type objects (section :ref:`typeobjects`).

1663

1664

1665

-.. ctype:: PyClassObject

1666

+.. c:type:: PyClassObject

1667

1668

The C structure of the objects used to describe built-in classes.

1669

1670

1671

-.. cvar:: PyObject* PyClass_Type

1672

+.. c:var:: PyObject* PyClass_Type

1673

1674

.. index:: single: ClassType (in module types)

1675

1676

@@ -25,13 +25,13 @@

1677

``types.ClassType`` in the Python layer.

1678

1679

1680

-.. cfunction:: int PyClass_Check(PyObject *o)

1681

+.. c:function:: int PyClass_Check(PyObject *o)

1682

1683

Return true if the object *o* is a class object, including instances of types

1684

derived from the standard class object. Return false in all other cases.

1685

1686

1687

-.. cfunction:: int PyClass_IsSubclass(PyObject *klass, PyObject *base)

1688

+.. c:function:: int PyClass_IsSubclass(PyObject *klass, PyObject *base)

1689

1690

Return true if *klass* is a subclass of *base*. Return false in all other cases.

1691

1692

@@ -41,23 +41,23 @@

1693

There are very few functions specific to instance objects.

1694

1695

1696

-.. cvar:: PyTypeObject PyInstance_Type

1697

+.. c:var:: PyTypeObject PyInstance_Type

1698

1699

Type object for class instances.

1700

1701

1702

-.. cfunction:: int PyInstance_Check(PyObject *obj)

1703

+.. c:function:: int PyInstance_Check(PyObject *obj)

1704

1705

Return true if *obj* is an instance.

1706

1707

1708

-.. cfunction:: PyObject* PyInstance_New(PyObject *class, PyObject *arg, PyObject *kw)

1709

+.. c:function:: PyObject* PyInstance_New(PyObject *class, PyObject *arg, PyObject *kw)

1710

1711

Create a new instance of a specific class. The parameters *arg* and *kw* are

1712

used as the positional and keyword parameters to the object's constructor.

1713

1714

1715

-.. cfunction:: PyObject* PyInstance_NewRaw(PyObject *class, PyObject *dict)

1716

+.. c:function:: PyObject* PyInstance_NewRaw(PyObject *class, PyObject *dict)

1717

1718

Create a new instance of a specific class without calling its constructor.

1719

*class* is the class of new object. The *dict* parameter will be used as the

1720

diff -r 8527427914a2 Doc/c-api/cobject.rst

1721

--- a/Doc/c-api/cobject.rst

1722

+++ b/Doc/c-api/cobject.rst

1723

@@ -13,47 +13,47 @@

1724

The CObject API is deprecated as of Python 2.7. Please switch to the new

1725

:ref:`capsules` API.

1726

1727

-.. ctype:: PyCObject

1728

+.. c:type:: PyCObject

1729

1730

- This subtype of :ctype:`PyObject` represents an opaque value, useful for C

1731

- extension modules who need to pass an opaque value (as a :ctype:`void\*`

1732

+ This subtype of :c:type:`PyObject` represents an opaque value, useful for C

1733

+ extension modules who need to pass an opaque value (as a :c:type:`void\*`

1734

pointer) through Python code to other C code. It is often used to make a C

1735

function pointer defined in one module available to other modules, so the

1736

regular import mechanism can be used to access C APIs defined in dynamically

1737

loaded modules.

1738

1739

1740

-.. cfunction:: int PyCObject_Check(PyObject *p)

1741

+.. c:function:: int PyCObject_Check(PyObject *p)

1742

1743

- Return true if its argument is a :ctype:`PyCObject`.

1744

+ Return true if its argument is a :c:type:`PyCObject`.

1745

1746

1747

-.. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))

1748

+.. c:function:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))

1749

1750

- Create a :ctype:`PyCObject` from the ``void *`` *cobj*. The *destr* function

1751

+ Create a :c:type:`PyCObject` from the ``void *`` *cobj*. The *destr* function

1752

will be called when the object is reclaimed, unless it is *NULL*.

1753

1754

1755

-.. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))

1756

+.. c:function:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))

1757

1758

- Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*. The *destr*

1759

+ Create a :c:type:`PyCObject` from the :c:type:`void \*` *cobj*. The *destr*

1760

function will be called when the object is reclaimed. The *desc* argument can

1761

be used to pass extra callback data for the destructor function.

1762

1763

1764

-.. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self)

1765

+.. c:function:: void* PyCObject_AsVoidPtr(PyObject* self)

1766

1767

- Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was

1768

+ Return the object :c:type:`void \*` that the :c:type:`PyCObject` *self* was

1769

created with.

1770

1771

1772

-.. cfunction:: void* PyCObject_GetDesc(PyObject* self)

1773

+.. c:function:: void* PyCObject_GetDesc(PyObject* self)

1774

1775

- Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was

1776

+ Return the description :c:type:`void \*` that the :c:type:`PyCObject` *self* was

1777

created with.

1778

1779

1780

-.. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)

1781

+.. c:function:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)

1782

1783

- Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not

1784

+ Set the void pointer inside *self* to *cobj*. The :c:type:`PyCObject` must not

1785

have an associated destructor. Return true on success, false on failure.

1786

diff -r 8527427914a2 Doc/c-api/code.rst

1787

--- a/Doc/c-api/code.rst

1788

+++ b/Doc/c-api/code.rst

1789

@@ -15,35 +15,35 @@

1790

Each one represents a chunk of executable code that hasn't yet been

1791

bound into a function.

1792

1793

-.. ctype:: PyCodeObject

1794

+.. c:type:: PyCodeObject

1795

1796

The C structure of the objects used to describe code objects. The

1797

fields of this type are subject to change at any time.

1798

1799

1800

-.. cvar:: PyTypeObject PyCode_Type

1801

+.. c:var:: PyTypeObject PyCode_Type

1802

1803

- This is an instance of :ctype:`PyTypeObject` representing the Python

1804

+ This is an instance of :c:type:`PyTypeObject` representing the Python

1805

:class:`code` type.

1806

1807

1808

-.. cfunction:: int PyCode_Check(PyObject *co)

1809

+.. c:function:: int PyCode_Check(PyObject *co)

1810

1811

Return true if *co* is a :class:`code` object

1812

1813

-.. cfunction:: int PyCode_GetNumFree(PyObject *co)

1814

+.. c:function:: int PyCode_GetNumFree(PyObject *co)

1815

1816

Return the number of free variables in *co*.

1817

1818

-.. cfunction:: PyCodeObject *PyCode_New(int argcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)

1819

+.. c:function:: PyCodeObject *PyCode_New(int argcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)

1820

1821

Return a new code object. If you need a dummy code object to

1822

- create a frame, use :cfunc:`PyCode_NewEmpty` instead. Calling

1823

- :cfunc:`PyCode_New` directly can bind you to a precise Python

1824

+ create a frame, use :c:func:`PyCode_NewEmpty` instead. Calling

1825

+ :c:func:`PyCode_New` directly can bind you to a precise Python

1826

version since the definition of the bytecode changes often.

1827

1828

1829

-.. cfunction:: int PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)

1830

+.. c:function:: int PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)

1831

1832

Return a new empty code object with the specified filename,

1833

function name, and first line number. It is illegal to

1834

diff -r 8527427914a2 Doc/c-api/codec.rst

1835

--- a/Doc/c-api/codec.rst

1836

+++ b/Doc/c-api/codec.rst

1837

@@ -3,19 +3,19 @@

1838

Codec registry and support functions

1839

====================================

1840

1841

-.. cfunction:: int PyCodec_Register(PyObject *search_function)

1842

+.. c:function:: int PyCodec_Register(PyObject *search_function)

1843

1844

Register a new codec search function.

1845

1846

As side effect, this tries to load the :mod:`encodings` package, if not yet

1847

done, to make sure that it is always first in the list of search functions.

1848

1849

-.. cfunction:: int PyCodec_KnownEncoding(const char *encoding)

1850

+.. c:function:: int PyCodec_KnownEncoding(const char *encoding)

1851

1852

Return ``1`` or ``0`` depending on whether there is a registered codec for

1853

the given *encoding*.

1854

1855

-.. cfunction:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)

1856

+.. c:function:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)

1857

1858

Generic codec based encoding API.

1859

1860

@@ -24,7 +24,7 @@

1861

be *NULL* to use the default method defined for the codec. Raises a

1862

:exc:`LookupError` if no encoder can be found.

1863

1864

-.. cfunction:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)

1865

+.. c:function:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)

1866

1867

Generic codec based decoding API.

1868

1869

@@ -42,27 +42,27 @@

1870

effectively case-insensitive. If no codec is found, a :exc:`KeyError` is set

1871

and *NULL* returned.

1872

1873

-.. cfunction:: PyObject* PyCodec_Encoder(const char *encoding)

1874

+.. c:function:: PyObject* PyCodec_Encoder(const char *encoding)

1875

1876

Get an encoder function for the given *encoding*.

1877

1878

-.. cfunction:: PyObject* PyCodec_Decoder(const char *encoding)

1879

+.. c:function:: PyObject* PyCodec_Decoder(const char *encoding)

1880

1881

Get a decoder function for the given *encoding*.

1882

1883

-.. cfunction:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)

1884

+.. c:function:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)

1885

1886

Get an :class:`IncrementalEncoder` object for the given *encoding*.

1887

1888

-.. cfunction:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)

1889

+.. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)

1890

1891

Get an :class:`IncrementalDecoder` object for the given *encoding*.

1892

1893

-.. cfunction:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)

1894

+.. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)

1895

1896

Get a :class:`StreamReader` factory function for the given *encoding*.

1897

1898

-.. cfunction:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)

1899

+.. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)

1900

1901

Get a :class:`StreamWriter` factory function for the given *encoding*.

1902

1903

@@ -70,7 +70,7 @@

1904

Registry API for Unicode encoding error handlers

1905

------------------------------------------------

1906

1907

-.. cfunction:: int PyCodec_RegisterError(const char *name, PyObject *error)

1908

+.. c:function:: int PyCodec_RegisterError(const char *name, PyObject *error)

1909

1910

Register the error handling callback function *error* under the given *name*.

1911

This callback function will be called by a codec when it encounters

1912

@@ -89,29 +89,29 @@

1913

1914

Return ``0`` on success, ``-1`` on error.

1915

1916

-.. cfunction:: PyObject* PyCodec_LookupError(const char *name)

1917

+.. c:function:: PyObject* PyCodec_LookupError(const char *name)

1918

1919

Lookup the error handling callback function registered under *name*. As a

1920

special case *NULL* can be passed, in which case the error handling callback

1921

for "strict" will be returned.

1922

1923

-.. cfunction:: PyObject* PyCodec_StrictErrors(PyObject *exc)

1924

+.. c:function:: PyObject* PyCodec_StrictErrors(PyObject *exc)

1925

1926

Raise *exc* as an exception.

1927

1928

-.. cfunction:: PyObject* PyCodec_IgnoreErrors(PyObject *exc)

1929

+.. c:function:: PyObject* PyCodec_IgnoreErrors(PyObject *exc)

1930

1931

Ignore the unicode error, skipping the faulty input.

1932

1933

-.. cfunction:: PyObject* PyCodec_ReplaceErrors(PyObject *exc)

1934

+.. c:function:: PyObject* PyCodec_ReplaceErrors(PyObject *exc)

1935

1936

Replace the unicode encode error with ``?`` or ``U+FFFD``.

1937

1938

-.. cfunction:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)

1939

+.. c:function:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)

1940

1941

Replace the unicode encode error with XML character references.

1942

1943

-.. cfunction:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)

1944

+.. c:function:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)

1945

1946

Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and

1947

``\U``).

1948

diff -r 8527427914a2 Doc/c-api/complex.rst

1949

--- a/Doc/c-api/complex.rst

1950

+++ b/Doc/c-api/complex.rst

1951

@@ -21,7 +21,7 @@

1952

pointers. This is consistent throughout the API.

1953

1954

1955

-.. ctype:: Py_complex

1956

+.. c:type:: Py_complex

1957

1958

The C structure which corresponds to the value portion of a Python complex

1959

number object. Most of the functions for dealing with complex number objects

1960

@@ -34,97 +34,104 @@

1961

} Py_complex;

1962

1963

1964

-.. cfunction:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)

1965

+.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)

1966

1967

- Return the sum of two complex numbers, using the C :ctype:`Py_complex`

1968

+ Return the sum of two complex numbers, using the C :c:type:`Py_complex`

1969

representation.

1970

1971

1972

-.. cfunction:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)

1973

+.. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)

1974

1975

Return the difference between two complex numbers, using the C

1976

- :ctype:`Py_complex` representation.

1977

+ :c:type:`Py_complex` representation.

1978

1979

1980

-.. cfunction:: Py_complex _Py_c_neg(Py_complex complex)

1981

+.. c:function:: Py_complex _Py_c_neg(Py_complex complex)

1982

1983

Return the negation of the complex number *complex*, using the C

1984

- :ctype:`Py_complex` representation.

1985

+ :c:type:`Py_complex` representation.

1986

1987

1988

-.. cfunction:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)

1989

+.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)

1990

1991

- Return the product of two complex numbers, using the C :ctype:`Py_complex`

1992

+ Return the product of two complex numbers, using the C :c:type:`Py_complex`

1993

representation.

1994

1995

1996

-.. cfunction:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)

1997

+.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)

1998

1999

- Return the quotient of two complex numbers, using the C :ctype:`Py_complex`

2000

+ Return the quotient of two complex numbers, using the C :c:type:`Py_complex`

2001

representation.

2002

2003

+ If *divisor* is null, this method returns zero and sets

2004

+ :c:data:`errno` to :c:data:`EDOM`.

2005

2006

-.. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)

2007

2008

- Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex`

2009

+.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)

2010

+

2011

+ Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`

2012

representation.

2013

2014

+ If *num* is null and *exp* is not a positive real number,

2015

+ this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`.

2016

+

2017

2018

Complex Numbers as Python Objects

2019

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

2020

2021

2022

-.. ctype:: PyComplexObject

2023

+.. c:type:: PyComplexObject

2024

2025

- This subtype of :ctype:`PyObject` represents a Python complex number object.

2026

+ This subtype of :c:type:`PyObject` represents a Python complex number object.

2027

2028

2029

-.. cvar:: PyTypeObject PyComplex_Type

2030

+.. c:var:: PyTypeObject PyComplex_Type

2031

2032

- This instance of :ctype:`PyTypeObject` represents the Python complex number

2033

+ This instance of :c:type:`PyTypeObject` represents the Python complex number

2034

type. It is the same object as ``complex`` and ``types.ComplexType``.

2035

2036

2037

-.. cfunction:: int PyComplex_Check(PyObject *p)

2038

+.. c:function:: int PyComplex_Check(PyObject *p)

2039

2040

- Return true if its argument is a :ctype:`PyComplexObject` or a subtype of

2041

- :ctype:`PyComplexObject`.

2042

+ Return true if its argument is a :c:type:`PyComplexObject` or a subtype of

2043

+ :c:type:`PyComplexObject`.

2044

2045

.. versionchanged:: 2.2

2046

Allowed subtypes to be accepted.

2047

2048

2049

-.. cfunction:: int PyComplex_CheckExact(PyObject *p)

2050

+.. c:function:: int PyComplex_CheckExact(PyObject *p)

2051

2052

- Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of

2053

- :ctype:`PyComplexObject`.

2054

+ Return true if its argument is a :c:type:`PyComplexObject`, but not a subtype of

2055

+ :c:type:`PyComplexObject`.

2056

2057

.. versionadded:: 2.2

2058

2059

2060

-.. cfunction:: PyObject* PyComplex_FromCComplex(Py_complex v)

2061

+.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)

2062

2063

- Create a new Python complex number object from a C :ctype:`Py_complex` value.

2064

+ Create a new Python complex number object from a C :c:type:`Py_complex` value.

2065

2066

2067

-.. cfunction:: PyObject* PyComplex_FromDoubles(double real, double imag)

2068

+.. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)

2069

2070

- Return a new :ctype:`PyComplexObject` object from *real* and *imag*.

2071

+ Return a new :c:type:`PyComplexObject` object from *real* and *imag*.

2072

2073

2074

-.. cfunction:: double PyComplex_RealAsDouble(PyObject *op)

2075

+.. c:function:: double PyComplex_RealAsDouble(PyObject *op)

2076

2077

- Return the real part of *op* as a C :ctype:`double`.

2078

+ Return the real part of *op* as a C :c:type:`double`.

2079

2080

2081

-.. cfunction:: double PyComplex_ImagAsDouble(PyObject *op)

2082

+.. c:function:: double PyComplex_ImagAsDouble(PyObject *op)

2083

2084

- Return the imaginary part of *op* as a C :ctype:`double`.

2085

+ Return the imaginary part of *op* as a C :c:type:`double`.

2086

2087

2088

-.. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op)

2089

+.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)

2090

2091

- Return the :ctype:`Py_complex` value of the complex number *op*.

2092

+ Return the :c:type:`Py_complex` value of the complex number *op*.

2093

+ Upon failure, this method returns ``-1.0`` as a real value.

2094

2095

.. versionchanged:: 2.6

2096

If *op* is not a Python complex number object but has a :meth:`__complex__`

2097

diff -r 8527427914a2 Doc/c-api/concrete.rst

2098

--- a/Doc/c-api/concrete.rst

2099

+++ b/Doc/c-api/concrete.rst

2100

@@ -11,7 +11,7 @@

2101

Passing them an object of the wrong type is not a good idea; if you receive an

2102

object from a Python program and you are not sure that it has the right type,

2103

you must perform a type check first; for example, to check that an object is a

2104

-dictionary, use :cfunc:`PyDict_Check`. The chapter is structured like the

2105

+dictionary, use :c:func:`PyDict_Check`. The chapter is structured like the

2106

"family tree" of Python object types.

2107

2108

.. warning::

2109

diff -r 8527427914a2 Doc/c-api/conversion.rst

2110

--- a/Doc/c-api/conversion.rst

2111

+++ b/Doc/c-api/conversion.rst

2112

@@ -8,20 +8,20 @@

2113

Functions for number conversion and formatted string output.

2114

2115

2116

-.. cfunction:: int PyOS_snprintf(char *str, size_t size, const char *format, ...)

2117

+.. c:function:: int PyOS_snprintf(char *str, size_t size, const char *format, ...)

2118

2119

Output not more than *size* bytes to *str* according to the format string

2120

*format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.

2121

2122

2123

-.. cfunction:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

2124

+.. c:function:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

2125

2126

Output not more than *size* bytes to *str* according to the format string

2127

*format* and the variable argument list *va*. Unix man page

2128

:manpage:`vsnprintf(2)`.

2129

2130

-:cfunc:`PyOS_snprintf` and :cfunc:`PyOS_vsnprintf` wrap the Standard C library

2131

-functions :cfunc:`snprintf` and :cfunc:`vsnprintf`. Their purpose is to

2132

+:c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C library

2133

+functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose is to

2134

guarantee consistent behavior in corner cases, which the Standard C functions do

2135

not.

2136

2137

@@ -30,7 +30,7 @@

2138

Both functions require that ``str != NULL``, ``size > 0`` and ``format !=

2139

NULL``.

2140

2141

-If the platform doesn't have :cfunc:`vsnprintf` and the buffer size needed to

2142

+If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed to

2143

avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a

2144

*Py_FatalError*.

2145

2146

@@ -51,9 +51,9 @@

2147

The following functions provide locale-independent string to number conversions.

2148

2149

2150

-.. cfunction:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

2151

+.. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

2152

2153

- Convert a string ``s`` to a :ctype:`double`, raising a Python

2154

+ Convert a string ``s`` to a :c:type:`double`, raising a Python

2155

exception on failure. The set of accepted strings corresponds to

2156

the set of strings accepted by Python's :func:`float` constructor,

2157

except that ``s`` must not have leading or trailing whitespace.

2158

@@ -85,13 +85,13 @@

2159

.. versionadded:: 2.7

2160

2161

2162

-.. cfunction:: double PyOS_ascii_strtod(const char *nptr, char **endptr)

2163

+.. c:function:: double PyOS_ascii_strtod(const char *nptr, char **endptr)

2164

2165

- Convert a string to a :ctype:`double`. This function behaves like the Standard C

2166

- function :cfunc:`strtod` does in the C locale. It does this without changing the

2167

+ Convert a string to a :c:type:`double`. This function behaves like the Standard C

2168

+ function :c:func:`strtod` does in the C locale. It does this without changing the

2169

current locale, since that would not be thread-safe.

2170

2171

- :cfunc:`PyOS_ascii_strtod` should typically be used for reading configuration

2172

+ :c:func:`PyOS_ascii_strtod` should typically be used for reading configuration

2173

files or other non-user input that should be locale independent.

2174

2175

See the Unix man page :manpage:`strtod(2)` for details.

2176

@@ -99,14 +99,14 @@

2177

.. versionadded:: 2.4

2178

2179

.. deprecated:: 2.7

2180

- Use :cfunc:`PyOS_string_to_double` instead.

2181

+ Use :c:func:`PyOS_string_to_double` instead.

2182

2183

2184

2185

-.. cfunction:: char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)

2186

+.. c:function:: char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)

2187

2188

- Convert a :ctype:`double` to a string using the ``'.'`` as the decimal

2189

- separator. *format* is a :cfunc:`printf`\ -style format string specifying the

2190

+ Convert a :c:type:`double` to a string using the ``'.'`` as the decimal

2191

+ separator. *format* is a :c:func:`printf`\ -style format string specifying the

2192

number format. Allowed conversion characters are ``'e'``, ``'E'``, ``'f'``,

2193

``'F'``, ``'g'`` and ``'G'``.

2194

2195

@@ -119,9 +119,9 @@

2196

instead.

2197

2198

2199

-.. cfunction:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)

2200

+.. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)

2201

2202

- Convert a :ctype:`double` *val* to a string using supplied

2203

+ Convert a :c:type:`double` *val* to a string using supplied

2204

*format_code*, *precision*, and *flags*.

2205

2206

*format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,

2207

@@ -139,7 +139,7 @@

2208

like an integer.

2209

2210

* *Py_DTSF_ALT* means to apply "alternate" formatting rules. See the

2211

- documentation for the :cfunc:`PyOS_snprintf` ``'#'`` specifier for

2212

+ documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for

2213

details.

2214

2215

If *ptype* is non-NULL, then the value it points to will be set to one of

2216

@@ -148,34 +148,34 @@

2217

2218

The return value is a pointer to *buffer* with the converted string or

2219

*NULL* if the conversion failed. The caller is responsible for freeing the

2220

- returned string by calling :cfunc:`PyMem_Free`.

2221

+ returned string by calling :c:func:`PyMem_Free`.

2222

2223

.. versionadded:: 2.7

2224

2225

2226

-.. cfunction:: double PyOS_ascii_atof(const char *nptr)

2227

+.. c:function:: double PyOS_ascii_atof(const char *nptr)

2228

2229

- Convert a string to a :ctype:`double` in a locale-independent way.

2230

+ Convert a string to a :c:type:`double` in a locale-independent way.

2231

2232

See the Unix man page :manpage:`atof(2)` for details.

2233

2234

.. versionadded:: 2.4

2235

2236

.. deprecated:: 3.1

2237

- Use :cfunc:`PyOS_string_to_double` instead.

2238

+ Use :c:func:`PyOS_string_to_double` instead.

2239

2240

2241

-.. cfunction:: char* PyOS_stricmp(char *s1, char *s2)

2242

+.. c:function:: char* PyOS_stricmp(char *s1, char *s2)

2243

2244

Case insensitive comparison of strings. The function works almost

2245

- identically to :cfunc:`strcmp` except that it ignores the case.

2246

+ identically to :c:func:`strcmp` except that it ignores the case.

2247

2248

.. versionadded:: 2.6

2249

2250

2251

-.. cfunction:: char* PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size)

2252

+.. c:function:: char* PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size)

2253

2254

Case insensitive comparison of strings. The function works almost

2255

- identically to :cfunc:`strncmp` except that it ignores the case.

2256

+ identically to :c:func:`strncmp` except that it ignores the case.

2257

2258

.. versionadded:: 2.6

2259

diff -r 8527427914a2 Doc/c-api/datetime.rst

2260

--- a/Doc/c-api/datetime.rst

2261

+++ b/Doc/c-api/datetime.rst

2262

@@ -8,89 +8,89 @@

2263

Various date and time objects are supplied by the :mod:`datetime` module.

2264

Before using any of these functions, the header file :file:`datetime.h` must be

2265

included in your source (note that this is not included by :file:`Python.h`),

2266

-and the macro :cmacro:`PyDateTime_IMPORT` must be invoked, usually as part of

2267

+and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of

2268

the module initialisation function. The macro puts a pointer to a C structure

2269

-into a static variable, :cdata:`PyDateTimeAPI`, that is used by the following

2270

+into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following

2271

macros.

2272

2273

Type-check macros:

2274

2275

2276

-.. cfunction:: int PyDate_Check(PyObject *ob)

2277

+.. c:function:: int PyDate_Check(PyObject *ob)

2278

2279

- Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of

2280

- :cdata:`PyDateTime_DateType`. *ob* must not be *NULL*.

2281

+ Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of

2282

+ :c:data:`PyDateTime_DateType`. *ob* must not be *NULL*.

2283

2284

.. versionadded:: 2.4

2285

2286

2287

-.. cfunction:: int PyDate_CheckExact(PyObject *ob)

2288

+.. c:function:: int PyDate_CheckExact(PyObject *ob)

2289

2290

- Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be

2291

+ Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be

2292

*NULL*.

2293

2294

.. versionadded:: 2.4

2295

2296

2297

-.. cfunction:: int PyDateTime_Check(PyObject *ob)

2298

+.. c:function:: int PyDateTime_Check(PyObject *ob)

2299

2300

- Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType` or a subtype of

2301

- :cdata:`PyDateTime_DateTimeType`. *ob* must not be *NULL*.

2302

+ Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of

2303

+ :c:data:`PyDateTime_DateTimeType`. *ob* must not be *NULL*.

2304

2305

.. versionadded:: 2.4

2306

2307

2308

-.. cfunction:: int PyDateTime_CheckExact(PyObject *ob)

2309

+.. c:function:: int PyDateTime_CheckExact(PyObject *ob)

2310

2311

- Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not

2312

+ Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not

2313

be *NULL*.

2314

2315

.. versionadded:: 2.4

2316

2317

2318

-.. cfunction:: int PyTime_Check(PyObject *ob)

2319

+.. c:function:: int PyTime_Check(PyObject *ob)

2320

2321

- Return true if *ob* is of type :cdata:`PyDateTime_TimeType` or a subtype of

2322

- :cdata:`PyDateTime_TimeType`. *ob* must not be *NULL*.

2323

+ Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of

2324

+ :c:data:`PyDateTime_TimeType`. *ob* must not be *NULL*.

2325

2326

.. versionadded:: 2.4

2327

2328

2329

-.. cfunction:: int PyTime_CheckExact(PyObject *ob)

2330

+.. c:function:: int PyTime_CheckExact(PyObject *ob)

2331

2332

- Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be

2333

+ Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be

2334

*NULL*.

2335

2336

.. versionadded:: 2.4

2337

2338

2339

-.. cfunction:: int PyDelta_Check(PyObject *ob)

2340

+.. c:function:: int PyDelta_Check(PyObject *ob)

2341

2342

- Return true if *ob* is of type :cdata:`PyDateTime_DeltaType` or a subtype of

2343

- :cdata:`PyDateTime_DeltaType`. *ob* must not be *NULL*.

2344

+ Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of

2345

+ :c:data:`PyDateTime_DeltaType`. *ob* must not be *NULL*.

2346

2347

.. versionadded:: 2.4

2348

2349

2350

-.. cfunction:: int PyDelta_CheckExact(PyObject *ob)

2351

+.. c:function:: int PyDelta_CheckExact(PyObject *ob)

2352

2353

- Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be

2354

+ Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be

2355

*NULL*.

2356

2357

.. versionadded:: 2.4

2358

2359

2360

-.. cfunction:: int PyTZInfo_Check(PyObject *ob)

2361

+.. c:function:: int PyTZInfo_Check(PyObject *ob)

2362

2363

- Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType` or a subtype of

2364

- :cdata:`PyDateTime_TZInfoType`. *ob* must not be *NULL*.

2365

+ Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of

2366

+ :c:data:`PyDateTime_TZInfoType`. *ob* must not be *NULL*.

2367

2368

.. versionadded:: 2.4

2369

2370

2371

-.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob)

2372

+.. c:function:: int PyTZInfo_CheckExact(PyObject *ob)

2373

2374

- Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be

2375

+ Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be

2376

*NULL*.

2377

2378

.. versionadded:: 2.4

2379

@@ -98,14 +98,14 @@

2380

Macros to create objects:

2381

2382

2383

-.. cfunction:: PyObject* PyDate_FromDate(int year, int month, int day)

2384

+.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)

2385

2386

Return a ``datetime.date`` object with the specified year, month and day.

2387

2388

.. versionadded:: 2.4

2389

2390

2391

-.. cfunction:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)

2392

+.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)

2393

2394

Return a ``datetime.datetime`` object with the specified year, month, day, hour,

2395

minute, second and microsecond.

2396

@@ -113,7 +113,7 @@

2397

.. versionadded:: 2.4

2398

2399

2400

-.. cfunction:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)

2401

+.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)

2402

2403

Return a ``datetime.time`` object with the specified hour, minute, second and

2404

microsecond.

2405

@@ -121,7 +121,7 @@

2406

.. versionadded:: 2.4

2407

2408

2409

-.. cfunction:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)

2410

+.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)

2411

2412

Return a ``datetime.timedelta`` object representing the given number of days,

2413

seconds and microseconds. Normalization is performed so that the resulting

2414

@@ -131,90 +131,90 @@

2415

.. versionadded:: 2.4

2416

2417

Macros to extract fields from date objects. The argument must be an instance of

2418

-:cdata:`PyDateTime_Date`, including subclasses (such as

2419

-:cdata:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is

2420

+:c:data:`PyDateTime_Date`, including subclasses (such as

2421

+:c:data:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is

2422

not checked:

2423

2424

2425

-.. cfunction:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)

2426

+.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)

2427

2428

Return the year, as a positive int.

2429

2430

.. versionadded:: 2.4

2431

2432

2433

-.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)

2434

+.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)

2435

2436

Return the month, as an int from 1 through 12.

2437

2438

.. versionadded:: 2.4

2439

2440

2441

-.. cfunction:: int PyDateTime_GET_DAY(PyDateTime_Date *o)

2442

+.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o)

2443

2444

Return the day, as an int from 1 through 31.

2445

2446

.. versionadded:: 2.4

2447

2448

Macros to extract fields from datetime objects. The argument must be an

2449

-instance of :cdata:`PyDateTime_DateTime`, including subclasses. The argument

2450

+instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument

2451

must not be *NULL*, and the type is not checked:

2452

2453

2454

-.. cfunction:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)

2455

+.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)

2456

2457

Return the hour, as an int from 0 through 23.

2458

2459

.. versionadded:: 2.4

2460

2461

2462

-.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)

2463

+.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)

2464

2465

Return the minute, as an int from 0 through 59.

2466

2467

.. versionadded:: 2.4

2468

2469

2470

-.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)

2471

+.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)

2472

2473

Return the second, as an int from 0 through 59.

2474

2475

.. versionadded:: 2.4

2476

2477

2478

-.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)

2479

+.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)

2480

2481

Return the microsecond, as an int from 0 through 999999.

2482

2483

.. versionadded:: 2.4

2484

2485

Macros to extract fields from time objects. The argument must be an instance of

2486

-:cdata:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*,

2487

+:c:data:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*,

2488

and the type is not checked:

2489

2490

2491

-.. cfunction:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)

2492

+.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)

2493

2494

Return the hour, as an int from 0 through 23.

2495

2496

.. versionadded:: 2.4

2497

2498

2499

-.. cfunction:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)

2500

+.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)

2501

2502

Return the minute, as an int from 0 through 59.

2503

2504

.. versionadded:: 2.4

2505

2506

2507

-.. cfunction:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)

2508

+.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)

2509

2510

Return the second, as an int from 0 through 59.

2511

2512

.. versionadded:: 2.4

2513

2514

2515

-.. cfunction:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)

2516

+.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)

2517

2518

Return the microsecond, as an int from 0 through 999999.

2519

2520

@@ -223,7 +223,7 @@

2521

Macros for the convenience of modules implementing the DB API:

2522

2523

2524

-.. cfunction:: PyObject* PyDateTime_FromTimestamp(PyObject *args)

2525

+.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)

2526

2527

Create and return a new ``datetime.datetime`` object given an argument tuple

2528

suitable for passing to ``datetime.datetime.fromtimestamp()``.

2529

@@ -231,7 +231,7 @@

2530

.. versionadded:: 2.4

2531

2532

2533

-.. cfunction:: PyObject* PyDate_FromTimestamp(PyObject *args)

2534

+.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)

2535

2536

Create and return a new ``datetime.date`` object given an argument tuple

2537

suitable for passing to ``datetime.date.fromtimestamp()``.

2538

diff -r 8527427914a2 Doc/c-api/descriptor.rst

2539

--- a/Doc/c-api/descriptor.rst

2540

+++ b/Doc/c-api/descriptor.rst

2541

@@ -9,39 +9,39 @@

2542

found in the dictionary of type objects.

2543

2544

2545

-.. cvar:: PyTypeObject PyProperty_Type

2546

+.. c:var:: PyTypeObject PyProperty_Type

2547

2548

The type object for the built-in descriptor types.

2549

2550

.. versionadded:: 2.2

2551

2552

2553

-.. cfunction:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)

2554

+.. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)

2555

2556

.. versionadded:: 2.2

2557

2558

2559

-.. cfunction:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)

2560

+.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)

2561

2562

.. versionadded:: 2.2

2563

2564

2565

-.. cfunction:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)

2566

+.. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)

2567

2568

.. versionadded:: 2.2

2569

2570

2571

-.. cfunction:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)

2572

+.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)

2573

2574

.. versionadded:: 2.2

2575

2576

2577

-.. cfunction:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)

2578

+.. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)

2579

2580

.. versionadded:: 2.3

2581

2582

2583

-.. cfunction:: int PyDescr_IsData(PyObject *descr)

2584

+.. c:function:: int PyDescr_IsData(PyObject *descr)

2585

2586

Return true if the descriptor objects *descr* describes a data attribute, or

2587

false if it describes a method. *descr* must be a descriptor object; there is

2588

@@ -50,6 +50,6 @@

2589

.. versionadded:: 2.2

2590

2591

2592

-.. cfunction:: PyObject* PyWrapper_New(PyObject *, PyObject *)

2593

+.. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)

2594

2595

.. versionadded:: 2.2

2596

diff -r 8527427914a2 Doc/c-api/dict.rst

2597

--- a/Doc/c-api/dict.rst

2598

+++ b/Doc/c-api/dict.rst

2599

@@ -8,23 +8,23 @@

2600

.. index:: object: dictionary

2601

2602

2603

-.. ctype:: PyDictObject

2604

+.. c:type:: PyDictObject

2605

2606

- This subtype of :ctype:`PyObject` represents a Python dictionary object.

2607

+ This subtype of :c:type:`PyObject` represents a Python dictionary object.

2608

2609

2610

-.. cvar:: PyTypeObject PyDict_Type

2611

+.. c:var:: PyTypeObject PyDict_Type

2612

2613

.. index::

2614

single: DictType (in module types)

2615

single: DictionaryType (in module types)

2616

2617

- This instance of :ctype:`PyTypeObject` represents the Python dictionary

2618

+ This instance of :c:type:`PyTypeObject` represents the Python dictionary

2619

type. This is exposed to Python programs as ``dict`` and

2620

``types.DictType``.

2621

2622

2623

-.. cfunction:: int PyDict_Check(PyObject *p)

2624

+.. c:function:: int PyDict_Check(PyObject *p)

2625

2626

Return true if *p* is a dict object or an instance of a subtype of the dict

2627

type.

2628

@@ -33,7 +33,7 @@

2629

Allowed subtypes to be accepted.

2630

2631

2632

-.. cfunction:: int PyDict_CheckExact(PyObject *p)

2633

+.. c:function:: int PyDict_CheckExact(PyObject *p)

2634

2635

Return true if *p* is a dict object, but not an instance of a subtype of

2636

the dict type.

2637

@@ -41,12 +41,12 @@

2638

.. versionadded:: 2.4

2639

2640

2641

-.. cfunction:: PyObject* PyDict_New()

2642

+.. c:function:: PyObject* PyDict_New()

2643

2644

Return a new empty dictionary, or *NULL* on failure.

2645

2646

2647

-.. cfunction:: PyObject* PyDictProxy_New(PyObject *dict)

2648

+.. c:function:: PyObject* PyDictProxy_New(PyObject *dict)

2649

2650

Return a proxy object for a mapping which enforces read-only behavior.

2651

This is normally used to create a proxy to prevent modification of the

2652

@@ -55,12 +55,12 @@

2653

.. versionadded:: 2.2

2654

2655

2656

-.. cfunction:: void PyDict_Clear(PyObject *p)

2657

+.. c:function:: void PyDict_Clear(PyObject *p)

2658

2659

Empty an existing dictionary of all key-value pairs.

2660

2661

2662

-.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)

2663

+.. c:function:: int PyDict_Contains(PyObject *p, PyObject *key)

2664

2665

Determine if dictionary *p* contains *key*. If an item in *p* is matches

2666

*key*, return ``1``, otherwise return ``0``. On error, return ``-1``.

2667

@@ -69,74 +69,74 @@

2668

.. versionadded:: 2.4

2669

2670

2671

-.. cfunction:: PyObject* PyDict_Copy(PyObject *p)

2672

+.. c:function:: PyObject* PyDict_Copy(PyObject *p)

2673

2674

Return a new dictionary that contains the same key-value pairs as *p*.

2675

2676

.. versionadded:: 1.6

2677

2678

2679

-.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

2680

+.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

2681

2682

Insert *value* into the dictionary *p* with a key of *key*. *key* must be

2683

:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return

2684

``0`` on success or ``-1`` on failure.

2685

2686

2687

-.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)

2688

+.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)

2689

2690

.. index:: single: PyString_FromString()

2691

2692

Insert *value* into the dictionary *p* using *key* as a key. *key* should

2693

- be a :ctype:`char\*`. The key object is created using

2694

+ be a :c:type:`char\*`. The key object is created using

2695

``PyString_FromString(key)``. Return ``0`` on success or ``-1`` on

2696

failure.

2697

2698

2699

-.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key)

2700

+.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)

2701

2702

Remove the entry in dictionary *p* with key *key*. *key* must be hashable;

2703

if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``

2704

on failure.

2705

2706

2707

-.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)

2708

+.. c:function:: int PyDict_DelItemString(PyObject *p, char *key)

2709

2710

Remove the entry in dictionary *p* which has a key specified by the string

2711

*key*. Return ``0`` on success or ``-1`` on failure.

2712

2713

2714

-.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)

2715

+.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)

2716

2717

Return the object from dictionary *p* which has a key *key*. Return *NULL*

2718

if the key *key* is not present, but *without* setting an exception.

2719

2720

2721

-.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)

2722

+.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)

2723

2724

- This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a

2725

- :ctype:`char\*`, rather than a :ctype:`PyObject\*`.

2726

+ This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a

2727

+ :c:type:`char\*`, rather than a :c:type:`PyObject\*`.

2728

2729

2730

-.. cfunction:: PyObject* PyDict_Items(PyObject *p)

2731

+.. c:function:: PyObject* PyDict_Items(PyObject *p)

2732

2733

- Return a :ctype:`PyListObject` containing all the items from the

2734

+ Return a :c:type:`PyListObject` containing all the items from the

2735

dictionary, as in the dictionary method :meth:`dict.items`.

2736

2737

2738

-.. cfunction:: PyObject* PyDict_Keys(PyObject *p)

2739

+.. c:function:: PyObject* PyDict_Keys(PyObject *p)

2740

2741

- Return a :ctype:`PyListObject` containing all the keys from the dictionary,

2742

+ Return a :c:type:`PyListObject` containing all the keys from the dictionary,

2743

as in the dictionary method :meth:`dict.keys`.

2744

2745

2746

-.. cfunction:: PyObject* PyDict_Values(PyObject *p)

2747

+.. c:function:: PyObject* PyDict_Values(PyObject *p)

2748

2749

- Return a :ctype:`PyListObject` containing all the values from the

2750

+ Return a :c:type:`PyListObject` containing all the values from the

2751

dictionary *p*, as in the dictionary method :meth:`dict.values`.

2752

2753

2754

-.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p)

2755

+.. c:function:: Py_ssize_t PyDict_Size(PyObject *p)

2756

2757

.. index:: builtin: len

2758

2759

@@ -144,18 +144,18 @@

2760

``len(p)`` on a dictionary.

2761

2762

.. versionchanged:: 2.5

2763

- This function returned an :ctype:`int` type. This might require changes

2764

+ This function returned an :c:type:`int` type. This might require changes

2765

in your code for properly supporting 64-bit systems.

2766

2767

2768

-.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)

2769

+.. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)

2770

2771

Iterate over all key-value pairs in the dictionary *p*. The

2772

- :ctype:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``

2773

+ :c:type:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``

2774

prior to the first call to this function to start the iteration; the

2775

function returns true for each pair in the dictionary, and false once all

2776

pairs have been reported. The parameters *pkey* and *pvalue* should either

2777

- point to :ctype:`PyObject\*` variables that will be filled in with each key

2778

+ point to :c:type:`PyObject\*` variables that will be filled in with each key

2779

and value, respectively, or may be *NULL*. Any references returned through

2780

them are borrowed. *ppos* should not be altered during iteration. Its

2781

value represents offsets within the internal dictionary structure, and

2782

@@ -192,15 +192,15 @@

2783

}

2784

2785

.. versionchanged:: 2.5

2786

- This function used an :ctype:`int *` type for *ppos*. This might require

2787

+ This function used an :c:type:`int *` type for *ppos*. This might require

2788

changes in your code for properly supporting 64-bit systems.

2789

2790

2791

-.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)

2792

+.. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)

2793

2794

Iterate over mapping object *b* adding key-value pairs to dictionary *a*.

2795

- *b* may be a dictionary, or any object supporting :cfunc:`PyMapping_Keys`

2796

- and :cfunc:`PyObject_GetItem`. If *override* is true, existing pairs in *a*

2797

+ *b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys`

2798

+ and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*

2799

will be replaced if a matching key is found in *b*, otherwise pairs will

2800

only be added if there is not a matching key in *a*. Return ``0`` on

2801

success or ``-1`` if an exception was raised.

2802

@@ -208,7 +208,7 @@

2803

.. versionadded:: 2.2

2804

2805

2806

-.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)

2807

+.. c:function:: int PyDict_Update(PyObject *a, PyObject *b)

2808

2809

This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in

2810

Python. Return ``0`` on success or ``-1`` if an exception was raised.

2811

@@ -216,7 +216,7 @@

2812

.. versionadded:: 2.2

2813

2814

2815

-.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)

2816

+.. c:function:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)

2817

2818

Update or merge into dictionary *a*, from the key-value pairs in *seq2*.

2819

*seq2* must be an iterable object producing iterable objects of length 2,

2820

diff -r 8527427914a2 Doc/c-api/exceptions.rst

2821

--- a/Doc/c-api/exceptions.rst

2822

+++ b/Doc/c-api/exceptions.rst

2823

@@ -9,12 +9,12 @@

2824

2825

The functions described in this chapter will let you handle and raise Python

2826

exceptions. It is important to understand some of the basics of Python

2827

-exception handling. It works somewhat like the Unix :cdata:`errno` variable:

2828

+exception handling. It works somewhat like the Unix :c:data:`errno` variable:

2829

there is a global indicator (per thread) of the last error that occurred. Most

2830

functions don't clear this on success, but will set it to indicate the cause of

2831

the error on failure. Most functions also return an error indicator, usually

2832

*NULL* if they are supposed to return a pointer, or ``-1`` if they return an

2833

-integer (exception: the :cfunc:`PyArg_\*` functions return ``1`` for success and

2834

+integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and

2835

``0`` for failure).

2836

2837

When a function must fail because some function it called failed, it generally

2838

@@ -41,7 +41,7 @@

2839

Either alphabetical or some kind of structure.

2840

2841

2842

-.. cfunction:: void PyErr_PrintEx(int set_sys_last_vars)

2843

+.. c:function:: void PyErr_PrintEx(int set_sys_last_vars)

2844

2845

Print a standard traceback to ``sys.stderr`` and clear the error indicator.

2846

Call this function only when the error indicator is set. (Otherwise it will

2847

@@ -52,35 +52,35 @@

2848

type, value and traceback of the printed exception, respectively.

2849

2850

2851

-.. cfunction:: void PyErr_Print()

2852

+.. c:function:: void PyErr_Print()

2853

2854

Alias for ``PyErr_PrintEx(1)``.

2855

2856

2857

-.. cfunction:: PyObject* PyErr_Occurred()

2858

+.. c:function:: PyObject* PyErr_Occurred()

2859

2860

Test whether the error indicator is set. If set, return the exception *type*

2861

- (the first argument to the last call to one of the :cfunc:`PyErr_Set\*`

2862

- functions or to :cfunc:`PyErr_Restore`). If not set, return *NULL*. You do not

2863

- own a reference to the return value, so you do not need to :cfunc:`Py_DECREF`

2864

+ (the first argument to the last call to one of the :c:func:`PyErr_Set\*`

2865

+ functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not

2866

+ own a reference to the return value, so you do not need to :c:func:`Py_DECREF`

2867

it.

2868

2869

.. note::

2870

2871

Do not compare the return value to a specific exception; use

2872

- :cfunc:`PyErr_ExceptionMatches` instead, shown below. (The comparison could

2873

+ :c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could

2874

easily fail since the exception may be an instance instead of a class, in the

2875

case of a class exception, or it may the a subclass of the expected exception.)

2876

2877

2878

-.. cfunction:: int PyErr_ExceptionMatches(PyObject *exc)

2879

+.. c:function:: int PyErr_ExceptionMatches(PyObject *exc)

2880

2881

Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This

2882

should only be called when an exception is actually set; a memory access

2883

violation will occur if no exception has been raised.

2884

2885

2886

-.. cfunction:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

2887

+.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

2888

2889

Return true if the *given* exception matches the exception in *exc*. If

2890

*exc* is a class object, this also returns true when *given* is an instance

2891

@@ -88,22 +88,22 @@

2892

recursively in subtuples) are searched for a match.

2893

2894

2895

-.. cfunction:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)

2896

+.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)

2897

2898

- Under certain circumstances, the values returned by :cfunc:`PyErr_Fetch` below

2899

+ Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below

2900

can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is

2901

not an instance of the same class. This function can be used to instantiate

2902

the class in that case. If the values are already normalized, nothing happens.

2903

The delayed normalization is implemented to improve performance.

2904

2905

2906

-.. cfunction:: void PyErr_Clear()

2907

+.. c:function:: void PyErr_Clear()

2908

2909

Clear the error indicator. If the error indicator is not set, there is no

2910

effect.

2911

2912

2913

-.. cfunction:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

2914

+.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

2915

2916

Retrieve the error indicator into three variables whose addresses are passed.

2917

If the error indicator is not set, set all three variables to *NULL*. If it is

2918

@@ -116,7 +116,7 @@

2919

by code that needs to save and restore the error indicator temporarily.

2920

2921

2922

-.. cfunction:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)

2923

+.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)

2924

2925

Set the error indicator from the three objects. If the error indicator is

2926

already set, it is cleared first. If the objects are *NULL*, the error

2927

@@ -131,111 +131,111 @@

2928

.. note::

2929

2930

This function is normally only used by code that needs to save and restore the

2931

- error indicator temporarily; use :cfunc:`PyErr_Fetch` to save the current

2932

+ error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current

2933

exception state.

2934

2935

2936

-.. cfunction:: void PyErr_SetString(PyObject *type, const char *message)

2937

+.. c:function:: void PyErr_SetString(PyObject *type, const char *message)

2938

2939

This is the most common way to set the error indicator. The first argument

2940

specifies the exception type; it is normally one of the standard exceptions,

2941

- e.g. :cdata:`PyExc_RuntimeError`. You need not increment its reference count.

2942

+ e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count.

2943

The second argument is an error message; it is converted to a string object.

2944

2945

2946

-.. cfunction:: void PyErr_SetObject(PyObject *type, PyObject *value)

2947

+.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)

2948

2949

- This function is similar to :cfunc:`PyErr_SetString` but lets you specify an

2950

+ This function is similar to :c:func:`PyErr_SetString` but lets you specify an

2951

arbitrary Python object for the "value" of the exception.

2952

2953

2954

-.. cfunction:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)

2955

+.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)

2956

2957

This function sets the error indicator and returns *NULL*. *exception*

2958

should be a Python exception class. The *format* and subsequent

2959

parameters help format the error message; they have the same meaning and

2960

- values as in :cfunc:`PyString_FromFormat`.

2961

+ values as in :c:func:`PyString_FromFormat`.

2962

2963

2964

-.. cfunction:: void PyErr_SetNone(PyObject *type)

2965

+.. c:function:: void PyErr_SetNone(PyObject *type)

2966

2967

This is a shorthand for ``PyErr_SetObject(type, Py_None)``.

2968

2969

2970

-.. cfunction:: int PyErr_BadArgument()

2971

+.. c:function:: int PyErr_BadArgument()

2972

2973

This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where

2974

*message* indicates that a built-in operation was invoked with an illegal

2975

argument. It is mostly for internal use.

2976

2977

2978

-.. cfunction:: PyObject* PyErr_NoMemory()

2979

+.. c:function:: PyObject* PyErr_NoMemory()

2980

2981

This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*

2982

so an object allocation function can write ``return PyErr_NoMemory();`` when it

2983

runs out of memory.

2984

2985

2986

-.. cfunction:: PyObject* PyErr_SetFromErrno(PyObject *type)

2987

+.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)

2988

2989

.. index:: single: strerror()

2990

2991

This is a convenience function to raise an exception when a C library function

2992

- has returned an error and set the C variable :cdata:`errno`. It constructs a

2993

- tuple object whose first item is the integer :cdata:`errno` value and whose

2994

- second item is the corresponding error message (gotten from :cfunc:`strerror`),

2995

+ has returned an error and set the C variable :c:data:`errno`. It constructs a

2996

+ tuple object whose first item is the integer :c:data:`errno` value and whose

2997

+ second item is the corresponding error message (gotten from :c:func:`strerror`),

2998

and then calls ``PyErr_SetObject(type, object)``. On Unix, when the

2999

- :cdata:`errno` value is :const:`EINTR`, indicating an interrupted system call,

3000

- this calls :cfunc:`PyErr_CheckSignals`, and if that set the error indicator,

3001

+ :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,

3002

+ this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,

3003

leaves it set to that. The function always returns *NULL*, so a wrapper

3004

function around a system call can write ``return PyErr_SetFromErrno(type);``

3005

when the system call returns an error.

3006

3007

3008

-.. cfunction:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)

3009

+.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)

3010

3011

- Similar to :cfunc:`PyErr_SetFromErrno`, with the additional behavior that if

3012

+ Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if

3013

*filename* is not *NULL*, it is passed to the constructor of *type* as a third

3014

parameter. In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,

3015

this is used to define the :attr:`filename` attribute of the exception instance.

3016

3017

3018

-.. cfunction:: PyObject* PyErr_SetFromWindowsErr(int ierr)

3019

+.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)

3020

3021

This is a convenience function to raise :exc:`WindowsError`. If called with

3022

- *ierr* of :cdata:`0`, the error code returned by a call to :cfunc:`GetLastError`

3023

- is used instead. It calls the Win32 function :cfunc:`FormatMessage` to retrieve

3024

- the Windows description of error code given by *ierr* or :cfunc:`GetLastError`,

3025

+ *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`

3026

+ is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve

3027

+ the Windows description of error code given by *ierr* or :c:func:`GetLastError`,

3028

then it constructs a tuple object whose first item is the *ierr* value and whose

3029

second item is the corresponding error message (gotten from

3030

- :cfunc:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,

3031

+ :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,

3032

object)``. This function always returns *NULL*. Availability: Windows.

3033

3034

3035

-.. cfunction:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

3036

+.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

3037

3038

- Similar to :cfunc:`PyErr_SetFromWindowsErr`, with an additional parameter

3039

+ Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter

3040

specifying the exception type to be raised. Availability: Windows.

3041

3042

.. versionadded:: 2.3

3043

3044

3045

-.. cfunction:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)

3046

+.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)

3047

3048

- Similar to :cfunc:`PyErr_SetFromWindowsErr`, with the additional behavior that

3049

+ Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that

3050

if *filename* is not *NULL*, it is passed to the constructor of

3051

:exc:`WindowsError` as a third parameter. Availability: Windows.

3052

3053

3054

-.. cfunction:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)

3055

+.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)

3056

3057

- Similar to :cfunc:`PyErr_SetFromWindowsErrWithFilename`, with an additional

3058

+ Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional

3059

parameter specifying the exception type to be raised. Availability: Windows.

3060

3061

.. versionadded:: 2.3

3062

3063

3064

-.. cfunction:: void PyErr_BadInternalCall()

3065

+.. c:function:: void PyErr_BadInternalCall()

3066

3067

This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,

3068

where *message* indicates that an internal operation (e.g. a Python/C API

3069

@@ -243,13 +243,13 @@

3070

use.

3071

3072

3073

-.. cfunction:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)

3074

+.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)

3075

3076

Issue a warning message. The *category* argument is a warning category (see

3077

below) or *NULL*; the *message* argument is a message string. *stacklevel* is a

3078

positive number giving a number of stack frames; the warning will be issued from

3079

the currently executing line of code in that stack frame. A *stacklevel* of 1

3080

- is the function calling :cfunc:`PyErr_WarnEx`, 2 is the function above that,

3081

+ is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,

3082

and so forth.

3083

3084

This function normally prints a warning message to *sys.stderr*; however, it is

3085

@@ -261,36 +261,36 @@

3086

is raised. (It is not possible to determine whether a warning message is

3087

actually printed, nor what the reason is for the exception; this is

3088

intentional.) If an exception is raised, the caller should do its normal

3089

- exception handling (for example, :cfunc:`Py_DECREF` owned references and return

3090

+ exception handling (for example, :c:func:`Py_DECREF` owned references and return

3091

an error value).

3092

3093

- Warning categories must be subclasses of :cdata:`Warning`; the default warning

3094

- category is :cdata:`RuntimeWarning`. The standard Python warning categories are

3095

+ Warning categories must be subclasses of :c:data:`Warning`; the default warning

3096

+ category is :c:data:`RuntimeWarning`. The standard Python warning categories are

3097

available as global variables whose names are ``PyExc_`` followed by the Python

3098

- exception name. These have the type :ctype:`PyObject\*`; they are all class

3099

- objects. Their names are :cdata:`PyExc_Warning`, :cdata:`PyExc_UserWarning`,

3100

- :cdata:`PyExc_UnicodeWarning`, :cdata:`PyExc_DeprecationWarning`,

3101

- :cdata:`PyExc_SyntaxWarning`, :cdata:`PyExc_RuntimeWarning`, and

3102

- :cdata:`PyExc_FutureWarning`. :cdata:`PyExc_Warning` is a subclass of

3103

- :cdata:`PyExc_Exception`; the other warning categories are subclasses of

3104

- :cdata:`PyExc_Warning`.

3105

+ exception name. These have the type :c:type:`PyObject\*`; they are all class

3106

+ objects. Their names are :c:data:`PyExc_Warning`, :c:data:`PyExc_UserWarning`,

3107

+ :c:data:`PyExc_UnicodeWarning`, :c:data:`PyExc_DeprecationWarning`,

3108

+ :c:data:`PyExc_SyntaxWarning`, :c:data:`PyExc_RuntimeWarning`, and

3109

+ :c:data:`PyExc_FutureWarning`. :c:data:`PyExc_Warning` is a subclass of

3110

+ :c:data:`PyExc_Exception`; the other warning categories are subclasses of

3111

+ :c:data:`PyExc_Warning`.

3112

3113

For information about warning control, see the documentation for the

3114

:mod:`warnings` module and the :option:`-W` option in the command line

3115

documentation. There is no C API for warning control.

3116

3117

3118

-.. cfunction:: int PyErr_Warn(PyObject *category, char *message)

3119

+.. c:function:: int PyErr_Warn(PyObject *category, char *message)

3120

3121

Issue a warning message. The *category* argument is a warning category (see

3122

below) or *NULL*; the *message* argument is a message string. The warning will

3123

- appear to be issued from the function calling :cfunc:`PyErr_Warn`, equivalent to

3124

- calling :cfunc:`PyErr_WarnEx` with a *stacklevel* of 1.

3125

+ appear to be issued from the function calling :c:func:`PyErr_Warn`, equivalent to

3126

+ calling :c:func:`PyErr_WarnEx` with a *stacklevel* of 1.

3127

3128

- Deprecated; use :cfunc:`PyErr_WarnEx` instead.

3129

+ Deprecated; use :c:func:`PyErr_WarnEx` instead.

3130

3131

3132

-.. cfunction:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)

3133

+.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)

3134

3135

Issue a warning message with explicit control over all warning attributes. This

3136

is a straightforward wrapper around the Python function

3137

@@ -299,15 +299,15 @@

3138

described there.

3139

3140

3141

-.. cfunction:: int PyErr_WarnPy3k(char *message, int stacklevel)

3142

+.. c:function:: int PyErr_WarnPy3k(char *message, int stacklevel)

3143

3144

Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel*

3145

- if the :cdata:`Py_Py3kWarningFlag` flag is enabled.

3146

+ if the :c:data:`Py_Py3kWarningFlag` flag is enabled.

3147

3148

.. versionadded:: 2.6

3149

3150

3151

-.. cfunction:: int PyErr_CheckSignals()

3152

+.. c:function:: int PyErr_CheckSignals()

3153

3154

.. index::

3155

module: signal

3156

@@ -324,21 +324,21 @@

3157

cleared if it was previously set.

3158

3159

3160

-.. cfunction:: void PyErr_SetInterrupt()

3161

+.. c:function:: void PyErr_SetInterrupt()

3162

3163

.. index::

3164

single: SIGINT

3165

single: KeyboardInterrupt (built-in exception)

3166

3167

This function simulates the effect of a :const:`SIGINT` signal arriving --- the

3168

- next time :cfunc:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will

3169

+ next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will

3170

be raised. It may be called without holding the interpreter lock.

3171

3172

.. % XXX This was described as obsolete, but is used in

3173

.. % thread.interrupt_main() (used from IDLE), so it's still needed.

3174

3175

3176

-.. cfunction:: int PySignal_SetWakeupFd(int fd)

3177

+.. c:function:: int PySignal_SetWakeupFd(int fd)

3178

3179

This utility function specifies a file descriptor to which a ``'\0'`` byte will

3180

be written whenever a signal is received. It returns the previous such file

3181

@@ -350,13 +350,13 @@

3182

.. versionadded:: 2.6

3183

3184

3185

-.. cfunction:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)

3186

+.. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)

3187

3188

- This utility function creates and returns a new exception object. The *name*

3189

+ This utility function creates and returns a new exception class. The *name*

3190

argument must be the name of the new exception, a C string of the form

3191

- ``module.class``. The *base* and *dict* arguments are normally *NULL*. This

3192

- creates a class object derived from :exc:`Exception` (accessible in C as

3193

- :cdata:`PyExc_Exception`).

3194

+ ``module.classname``. The *base* and *dict* arguments are normally *NULL*.

3195

+ This creates a class object derived from :exc:`Exception` (accessible in C as

3196

+ :c:data:`PyExc_Exception`).

3197

3198

The :attr:`__module__` attribute of the new class is set to the first part (up

3199

to the last dot) of the *name* argument, and the class name is set to the last

3200

@@ -365,16 +365,16 @@

3201

argument can be used to specify a dictionary of class variables and methods.

3202

3203

3204

-.. cfunction:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict)

3205

+.. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict)

3206

3207

- Same as :cfunc:`PyErr_NewException`, except that the new exception class can

3208

+ Same as :c:func:`PyErr_NewException`, except that the new exception class can

3209

easily be given a docstring: If *doc* is non-*NULL*, it will be used as the

3210

docstring for the exception class.

3211

3212

.. versionadded:: 2.7

3213

3214

3215

-.. cfunction:: void PyErr_WriteUnraisable(PyObject *obj)

3216

+.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)

3217

3218

This utility function prints a warning message to ``sys.stderr`` when an

3219

exception has been set but it is impossible for the interpreter to actually

3220

@@ -393,33 +393,33 @@

3221

3222

The following functions are used to create and modify Unicode exceptions from C.

3223

3224

-.. cfunction:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

3225

+.. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

3226

3227

Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,

3228

*object*, *length*, *start*, *end* and *reason*.

3229

3230

-.. cfunction:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

3231

+.. c:function:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

3232

3233

Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,

3234

*object*, *length*, *start*, *end* and *reason*.

3235

3236

-.. cfunction:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

3237

+.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

3238

3239

Create a :class:`UnicodeTranslateError` object with the attributes *object*,

3240

*length*, *start*, *end* and *reason*.

3241

3242

-.. cfunction:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)

3243

+.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)

3244

PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)

3245

3246

Return the *encoding* attribute of the given exception object.

3247

3248

-.. cfunction:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)

3249

+.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)

3250

PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)

3251

PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)

3252

3253

Return the *object* attribute of the given exception object.

3254

3255

-.. cfunction:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)

3256

+.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)

3257

int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)

3258

int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)

3259

3260

@@ -427,14 +427,14 @@

3261

*\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on

3262

failure.

3263

3264

-.. cfunction:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)

3265

+.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)

3266

int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)

3267

int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)

3268

3269

Set the *start* attribute of the given exception object to *start*. Return

3270

``0`` on success, ``-1`` on failure.

3271

3272

-.. cfunction:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)

3273

+.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)

3274

int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)

3275

int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)

3276

3277

@@ -442,20 +442,20 @@

3278

*\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on

3279

failure.

3280

3281

-.. cfunction:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)

3282

+.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)

3283

int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)

3284

int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)

3285

3286

Set the *end* attribute of the given exception object to *end*. Return ``0``

3287

on success, ``-1`` on failure.

3288

3289

-.. cfunction:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)

3290

+.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)

3291

PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)

3292

PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)

3293

3294

Return the *reason* attribute of the given exception object.

3295

3296

-.. cfunction:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)

3297

+.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)

3298

int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)

3299

int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)

3300

3301

@@ -471,12 +471,12 @@

3302

recursive code does not necessarily invoke Python code (which tracks its

3303

recursion depth automatically).

3304

3305

-.. cfunction:: int Py_EnterRecursiveCall(char *where)

3306

+.. c:function:: int Py_EnterRecursiveCall(char *where)

3307

3308

Marks a point where a recursive C-level call is about to be performed.

3309

3310

- If :const:`USE_STACKCHECK` is defined, this function checks if the the OS

3311

- stack overflowed using :cfunc:`PyOS_CheckStack`. In this is the case, it

3312

+ If :const:`USE_STACKCHECK` is defined, this function checks if the OS

3313

+ stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it

3314

sets a :exc:`MemoryError` and returns a nonzero value.

3315

3316

The function then checks if the recursion limit is reached. If this is the

3317

@@ -487,10 +487,10 @@

3318

concatenated to the :exc:`RuntimeError` message caused by the recursion depth

3319

limit.

3320

3321

-.. cfunction:: void Py_LeaveRecursiveCall()

3322

+.. c:function:: void Py_LeaveRecursiveCall()

3323

3324

- Ends a :cfunc:`Py_EnterRecursiveCall`. Must be called once for each

3325

- *successful* invocation of :cfunc:`Py_EnterRecursiveCall`.

3326

+ Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each

3327

+ *successful* invocation of :c:func:`Py_EnterRecursiveCall`.

3328

3329

3330

.. _standardexceptions:

3331

@@ -500,70 +500,70 @@

3332

3333

All standard Python exceptions are available as global variables whose names are

3334

``PyExc_`` followed by the Python exception name. These have the type

3335

-:ctype:`PyObject\*`; they are all class objects. For completeness, here are all

3336

+:c:type:`PyObject\*`; they are all class objects. For completeness, here are all

3337

the variables:

3338

3339

-+------------------------------------+----------------------------+----------+

3340

-| C Name | Python Name | Notes |

3341

-+====================================+============================+==========+

3342

-| :cdata:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) |

3343

-+------------------------------------+----------------------------+----------+

3344

-| :cdata:`PyExc_Exception` | :exc:`Exception` | \(1) |

3345

-+------------------------------------+----------------------------+----------+

3346

-| :cdata:`PyExc_StandardError` | :exc:`StandardError` | \(1) |

3347

-+------------------------------------+----------------------------+----------+

3348

-| :cdata:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |

3349

-+------------------------------------+----------------------------+----------+

3350

-| :cdata:`PyExc_LookupError` | :exc:`LookupError` | \(1) |

3351

-+------------------------------------+----------------------------+----------+

3352

-| :cdata:`PyExc_AssertionError` | :exc:`AssertionError` | |

3353

-+------------------------------------+----------------------------+----------+

3354

-| :cdata:`PyExc_AttributeError` | :exc:`AttributeError` | |

3355

-+------------------------------------+----------------------------+----------+

3356

-| :cdata:`PyExc_EOFError` | :exc:`EOFError` | |

3357

-+------------------------------------+----------------------------+----------+

3358

-| :cdata:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) |

3359

-+------------------------------------+----------------------------+----------+

3360

-| :cdata:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |

3361

-+------------------------------------+----------------------------+----------+

3362

-| :cdata:`PyExc_IOError` | :exc:`IOError` | |

3363

-+------------------------------------+----------------------------+----------+

3364

-| :cdata:`PyExc_ImportError` | :exc:`ImportError` | |

3365

-+------------------------------------+----------------------------+----------+

3366

-| :cdata:`PyExc_IndexError` | :exc:`IndexError` | |

3367

-+------------------------------------+----------------------------+----------+

3368

-| :cdata:`PyExc_KeyError` | :exc:`KeyError` | |

3369

-+------------------------------------+----------------------------+----------+

3370

-| :cdata:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |

3371

-+------------------------------------+----------------------------+----------+

3372

-| :cdata:`PyExc_MemoryError` | :exc:`MemoryError` | |

3373

-+------------------------------------+----------------------------+----------+

3374

-| :cdata:`PyExc_NameError` | :exc:`NameError` | |

3375

-+------------------------------------+----------------------------+----------+

3376

-| :cdata:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |

3377

-+------------------------------------+----------------------------+----------+

3378

-| :cdata:`PyExc_OSError` | :exc:`OSError` | |

3379

-+------------------------------------+----------------------------+----------+

3380

-| :cdata:`PyExc_OverflowError` | :exc:`OverflowError` | |

3381

-+------------------------------------+----------------------------+----------+

3382

-| :cdata:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |

3383

-+------------------------------------+----------------------------+----------+

3384

-| :cdata:`PyExc_RuntimeError` | :exc:`RuntimeError` | |

3385

-+------------------------------------+----------------------------+----------+

3386

-| :cdata:`PyExc_SyntaxError` | :exc:`SyntaxError` | |

3387

-+------------------------------------+----------------------------+----------+

3388

-| :cdata:`PyExc_SystemError` | :exc:`SystemError` | |

3389

-+------------------------------------+----------------------------+----------+

3390

-| :cdata:`PyExc_SystemExit` | :exc:`SystemExit` | |

3391

-+------------------------------------+----------------------------+----------+

3392

-| :cdata:`PyExc_TypeError` | :exc:`TypeError` | |

3393

-+------------------------------------+----------------------------+----------+

3394

-| :cdata:`PyExc_ValueError` | :exc:`ValueError` | |

3395

-+------------------------------------+----------------------------+----------+

3396

-| :cdata:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) |

3397

-+------------------------------------+----------------------------+----------+

3398

-| :cdata:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |

3399

-+------------------------------------+----------------------------+----------+

3400

++-------------------------------------+----------------------------+----------+

3401

+| C Name | Python Name | Notes |

3402

++=====================================+============================+==========+

3403

+| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) |

3404

++-------------------------------------+----------------------------+----------+

3405

+| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) |

3406

++-------------------------------------+----------------------------+----------+

3407

+| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) |

3408

++-------------------------------------+----------------------------+----------+

3409

+| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |

3410

++-------------------------------------+----------------------------+----------+

3411

+| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |

3412

++-------------------------------------+----------------------------+----------+

3413

+| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |

3414

++-------------------------------------+----------------------------+----------+

3415

+| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |

3416

++-------------------------------------+----------------------------+----------+

3417

+| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |

3418

++-------------------------------------+----------------------------+----------+

3419

+| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) |

3420

++-------------------------------------+----------------------------+----------+

3421

+| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |

3422

++-------------------------------------+----------------------------+----------+

3423

+| :c:data:`PyExc_IOError` | :exc:`IOError` | |

3424

++-------------------------------------+----------------------------+----------+

3425

+| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |

3426

++-------------------------------------+----------------------------+----------+

3427

+| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |

3428

++-------------------------------------+----------------------------+----------+

3429

+| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |

3430

++-------------------------------------+----------------------------+----------+

3431

+| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |

3432

++-------------------------------------+----------------------------+----------+

3433

+| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |

3434

++-------------------------------------+----------------------------+----------+

3435

+| :c:data:`PyExc_NameError` | :exc:`NameError` | |

3436

++-------------------------------------+----------------------------+----------+

3437

+| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |

3438

++-------------------------------------+----------------------------+----------+

3439

+| :c:data:`PyExc_OSError` | :exc:`OSError` | |

3440

++-------------------------------------+----------------------------+----------+

3441

+| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |

3442

++-------------------------------------+----------------------------+----------+

3443

+| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |

3444

++-------------------------------------+----------------------------+----------+

3445

+| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |

3446

++-------------------------------------+----------------------------+----------+

3447

+| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |

3448

++-------------------------------------+----------------------------+----------+

3449

+| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |

3450

++-------------------------------------+----------------------------+----------+

3451

+| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |

3452

++-------------------------------------+----------------------------+----------+

3453

+| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |

3454

++-------------------------------------+----------------------------+----------+

3455

+| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |

3456

++-------------------------------------+----------------------------+----------+

3457

+| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) |

3458

++-------------------------------------+----------------------------+----------+

3459

+| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |

3460

++-------------------------------------+----------------------------+----------+

3461

3462

.. index::

3463

single: PyExc_BaseException

3464

diff -r 8527427914a2 Doc/c-api/file.rst

3465

--- a/Doc/c-api/file.rst

3466

+++ b/Doc/c-api/file.rst

3467

@@ -7,78 +7,79 @@

3468

3469

.. index:: object: file

3470

3471

-Python's built-in file objects are implemented entirely on the :ctype:`FILE\*`

3472

+Python's built-in file objects are implemented entirely on the :c:type:`FILE\*`

3473

support from the C standard library. This is an implementation detail and may

3474

change in future releases of Python.

3475

3476

3477

-.. ctype:: PyFileObject

3478

+.. c:type:: PyFileObject

3479

3480

- This subtype of :ctype:`PyObject` represents a Python file object.

3481

+ This subtype of :c:type:`PyObject` represents a Python file object.

3482

3483

3484

-.. cvar:: PyTypeObject PyFile_Type

3485

+.. c:var:: PyTypeObject PyFile_Type

3486

3487

.. index:: single: FileType (in module types)

3488

3489

- This instance of :ctype:`PyTypeObject` represents the Python file type. This is

3490

+ This instance of :c:type:`PyTypeObject` represents the Python file type. This is

3491

exposed to Python programs as ``file`` and ``types.FileType``.

3492

3493

3494

-.. cfunction:: int PyFile_Check(PyObject *p)

3495

+.. c:function:: int PyFile_Check(PyObject *p)

3496

3497

- Return true if its argument is a :ctype:`PyFileObject` or a subtype of

3498

- :ctype:`PyFileObject`.

3499

+ Return true if its argument is a :c:type:`PyFileObject` or a subtype of

3500

+ :c:type:`PyFileObject`.

3501

3502

.. versionchanged:: 2.2

3503

Allowed subtypes to be accepted.

3504

3505

3506

-.. cfunction:: int PyFile_CheckExact(PyObject *p)

3507

+.. c:function:: int PyFile_CheckExact(PyObject *p)

3508

3509

- Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of

3510

- :ctype:`PyFileObject`.

3511

+ Return true if its argument is a :c:type:`PyFileObject`, but not a subtype of

3512

+ :c:type:`PyFileObject`.

3513

3514

.. versionadded:: 2.2

3515

3516

3517

-.. cfunction:: PyObject* PyFile_FromString(char *filename, char *mode)

3518

+.. c:function:: PyObject* PyFile_FromString(char *filename, char *mode)

3519

3520

.. index:: single: fopen()

3521

3522

On success, return a new file object that is opened on the file given by

3523

*filename*, with a file mode given by *mode*, where *mode* has the same

3524

- semantics as the standard C routine :cfunc:`fopen`. On failure, return *NULL*.

3525

+ semantics as the standard C routine :c:func:`fopen`. On failure, return *NULL*.

3526

3527

3528

-.. cfunction:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))

3529

+.. c:function:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))

3530

3531

- Create a new :ctype:`PyFileObject` from the already-open standard C file

3532

+ Create a new :c:type:`PyFileObject` from the already-open standard C file

3533

pointer, *fp*. The function *close* will be called when the file should be

3534

- closed. Return *NULL* on failure.

3535

+ closed. Return *NULL* and close the file using *close* on failure.

3536

+ *close* is optional and can be set to *NULL*.

3537

3538

3539

-.. cfunction:: FILE* PyFile_AsFile(PyObject \*p)

3540

+.. c:function:: FILE* PyFile_AsFile(PyObject \*p)

3541

3542

- Return the file object associated with *p* as a :ctype:`FILE\*`.

3543

+ Return the file object associated with *p* as a :c:type:`FILE\*`.

3544

3545

- If the caller will ever use the returned :ctype:`FILE\*` object while

3546

- the :term:`GIL` is released it must also call the :cfunc:`PyFile_IncUseCount` and

3547

- :cfunc:`PyFile_DecUseCount` functions described below as appropriate.

3548

+ If the caller will ever use the returned :c:type:`FILE\*` object while

3549

+ the :term:`GIL` is released it must also call the :c:func:`PyFile_IncUseCount` and

3550

+ :c:func:`PyFile_DecUseCount` functions described below as appropriate.

3551

3552

3553

-.. cfunction:: void PyFile_IncUseCount(PyFileObject \*p)

3554

+.. c:function:: void PyFile_IncUseCount(PyFileObject \*p)

3555

3556

Increments the PyFileObject's internal use count to indicate

3557

- that the underlying :ctype:`FILE\*` is being used.

3558

+ that the underlying :c:type:`FILE\*` is being used.

3559

This prevents Python from calling f_close() on it from another thread.

3560

- Callers of this must call :cfunc:`PyFile_DecUseCount` when they are

3561

- finished with the :ctype:`FILE\*`. Otherwise the file object will

3562

+ Callers of this must call :c:func:`PyFile_DecUseCount` when they are

3563

+ finished with the :c:type:`FILE\*`. Otherwise the file object will

3564

never be closed by Python.

3565

3566

The :term:`GIL` must be held while calling this function.

3567

3568

- The suggested use is to call this after :cfunc:`PyFile_AsFile` and before

3569

+ The suggested use is to call this after :c:func:`PyFile_AsFile` and before

3570

you release the GIL::

3571

3572

FILE *fp = PyFile_AsFile(p);

3573

@@ -93,11 +94,11 @@

3574

.. versionadded:: 2.6

3575

3576

3577

-.. cfunction:: void PyFile_DecUseCount(PyFileObject \*p)

3578

+.. c:function:: void PyFile_DecUseCount(PyFileObject \*p)

3579

3580

Decrements the PyFileObject's internal unlocked_count member to

3581

- indicate that the caller is done with its own use of the :ctype:`FILE\*`.

3582

- This may only be called to undo a prior call to :cfunc:`PyFile_IncUseCount`.

3583

+ indicate that the caller is done with its own use of the :c:type:`FILE\*`.

3584

+ This may only be called to undo a prior call to :c:func:`PyFile_IncUseCount`.

3585

3586

The :term:`GIL` must be held while calling this function (see the example

3587

above).

3588

@@ -105,7 +106,7 @@

3589

.. versionadded:: 2.6

3590

3591

3592

-.. cfunction:: PyObject* PyFile_GetLine(PyObject *p, int n)

3593

+.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n)

3594

3595

.. index:: single: EOFError (built-in exception)

3596

3597

@@ -119,20 +120,20 @@

3598

raised if the end of the file is reached immediately.

3599

3600

3601

-.. cfunction:: PyObject* PyFile_Name(PyObject *p)

3602

+.. c:function:: PyObject* PyFile_Name(PyObject *p)

3603

3604

Return the name of the file specified by *p* as a string object.

3605

3606

3607

-.. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n)

3608

+.. c:function:: void PyFile_SetBufSize(PyFileObject *p, int n)

3609

3610

.. index:: single: setvbuf()

3611

3612

- Available on systems with :cfunc:`setvbuf` only. This should only be called

3613

+ Available on systems with :c:func:`setvbuf` only. This should only be called

3614

immediately after file object creation.

3615

3616

3617

-.. cfunction:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)

3618

+.. c:function:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)

3619

3620

Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0

3621

on failure.

3622

@@ -140,7 +141,7 @@

3623

.. versionadded:: 2.3

3624

3625

3626

-.. cfunction:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)

3627

+.. c:function:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)

3628

3629

Set the file's encoding for Unicode output to *enc*, and its error

3630

mode to *err*. Return 1 on success and 0 on failure.

3631

@@ -148,7 +149,7 @@

3632

.. versionadded:: 2.6

3633

3634

3635

-.. cfunction:: int PyFile_SoftSpace(PyObject *p, int newflag)

3636

+.. c:function:: int PyFile_SoftSpace(PyObject *p, int newflag)

3637

3638

.. index:: single: softspace (file attribute)

3639

3640

@@ -162,7 +163,7 @@

3641

but doing so should not be needed.

3642

3643

3644

-.. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)

3645

+.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)

3646

3647

.. index:: single: Py_PRINT_RAW

3648

3649

@@ -172,7 +173,7 @@

3650

appropriate exception will be set.

3651

3652

3653

-.. cfunction:: int PyFile_WriteString(const char *s, PyObject *p)

3654

+.. c:function:: int PyFile_WriteString(const char *s, PyObject *p)

3655

3656

Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on

3657

failure; the appropriate exception will be set.

3658

diff -r 8527427914a2 Doc/c-api/float.rst

3659

--- a/Doc/c-api/float.rst

3660

+++ b/Doc/c-api/float.rst

3661

@@ -8,62 +8,64 @@

3662

.. index:: object: floating point

3663

3664

3665

-.. ctype:: PyFloatObject

3666

+.. c:type:: PyFloatObject

3667

3668

- This subtype of :ctype:`PyObject` represents a Python floating point object.

3669

+ This subtype of :c:type:`PyObject` represents a Python floating point object.

3670

3671

3672

-.. cvar:: PyTypeObject PyFloat_Type

3673

+.. c:var:: PyTypeObject PyFloat_Type

3674

3675

.. index:: single: FloatType (in modules types)

3676

3677

- This instance of :ctype:`PyTypeObject` represents the Python floating point

3678

+ This instance of :c:type:`PyTypeObject` represents the Python floating point

3679

type. This is the same object as ``float`` and ``types.FloatType``.

3680

3681

3682

-.. cfunction:: int PyFloat_Check(PyObject *p)

3683

+.. c:function:: int PyFloat_Check(PyObject *p)

3684

3685

- Return true if its argument is a :ctype:`PyFloatObject` or a subtype of

3686

- :ctype:`PyFloatObject`.

3687

+ Return true if its argument is a :c:type:`PyFloatObject` or a subtype of

3688

+ :c:type:`PyFloatObject`.

3689

3690

.. versionchanged:: 2.2

3691

Allowed subtypes to be accepted.

3692

3693

3694

-.. cfunction:: int PyFloat_CheckExact(PyObject *p)

3695

+.. c:function:: int PyFloat_CheckExact(PyObject *p)

3696

3697

- Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of

3698

- :ctype:`PyFloatObject`.

3699

+ Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of

3700

+ :c:type:`PyFloatObject`.

3701

3702

.. versionadded:: 2.2

3703

3704

3705

-.. cfunction:: PyObject* PyFloat_FromString(PyObject *str, char **pend)

3706

+.. c:function:: PyObject* PyFloat_FromString(PyObject *str, char **pend)

3707

3708

- Create a :ctype:`PyFloatObject` object based on the string value in *str*, or

3709

+ Create a :c:type:`PyFloatObject` object based on the string value in *str*, or

3710

*NULL* on failure. The *pend* argument is ignored. It remains only for

3711

backward compatibility.

3712

3713

3714

-.. cfunction:: PyObject* PyFloat_FromDouble(double v)

3715

+.. c:function:: PyObject* PyFloat_FromDouble(double v)

3716

3717

- Create a :ctype:`PyFloatObject` object from *v*, or *NULL* on failure.

3718

+ Create a :c:type:`PyFloatObject` object from *v*, or *NULL* on failure.

3719

3720

3721

-.. cfunction:: double PyFloat_AsDouble(PyObject *pyfloat)

3722

+.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)

3723

3724

- Return a C :ctype:`double` representation of the contents of *pyfloat*. If

3725

+ Return a C :c:type:`double` representation of the contents of *pyfloat*. If

3726

*pyfloat* is not a Python floating point object but has a :meth:`__float__`

3727

method, this method will first be called to convert *pyfloat* into a float.

3728

+ This method returns ``-1.0`` upon failure, so one should call

3729

+ :c:func:`PyErr_Occurred` to check for errors.

3730

3731

3732

-.. cfunction:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)

3733

+.. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)

3734

3735

- Return a C :ctype:`double` representation of the contents of *pyfloat*, but

3736

+ Return a C :c:type:`double` representation of the contents of *pyfloat*, but

3737

without error checking.

3738

3739

3740

-.. cfunction:: PyObject* PyFloat_GetInfo(void)

3741

+.. c:function:: PyObject* PyFloat_GetInfo(void)

3742

3743

Return a structseq instance which contains information about the

3744

precision, minimum and maximum values of a float. It's a thin wrapper

3745

@@ -72,21 +74,21 @@

3746

.. versionadded:: 2.6

3747

3748

3749

-.. cfunction:: double PyFloat_GetMax()

3750

+.. c:function:: double PyFloat_GetMax()

3751

3752

- Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`.

3753

+ Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`.

3754

3755

.. versionadded:: 2.6

3756

3757

3758

-.. cfunction:: double PyFloat_GetMin()

3759

+.. c:function:: double PyFloat_GetMin()

3760

3761

- Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`.

3762

+ Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.

3763

3764

.. versionadded:: 2.6

3765

3766

3767

-.. cfunction:: int PyFloat_ClearFreeList()

3768

+.. c:function:: int PyFloat_ClearFreeList()

3769

3770

Clear the float free list. Return the number of items that could not

3771

be freed.

3772

@@ -94,7 +96,7 @@

3773

.. versionadded:: 2.6

3774

3775

3776

-.. cfunction:: void PyFloat_AsString(char *buf, PyFloatObject *v)

3777

+.. c:function:: void PyFloat_AsString(char *buf, PyFloatObject *v)

3778

3779

Convert the argument *v* to a string, using the same rules as

3780

:func:`str`. The length of *buf* should be at least 100.

3781

@@ -106,7 +108,7 @@

3782

Use :func:`PyObject_Str` or :func:`PyOS_double_to_string` instead.

3783

3784

3785

-.. cfunction:: void PyFloat_AsReprString(char *buf, PyFloatObject *v)

3786

+.. c:function:: void PyFloat_AsReprString(char *buf, PyFloatObject *v)

3787

3788

Same as PyFloat_AsString, except uses the same rules as

3789

:func:`repr`. The length of *buf* should be at least 100.

3790

diff -r 8527427914a2 Doc/c-api/function.rst

3791

--- a/Doc/c-api/function.rst

3792

+++ b/Doc/c-api/function.rst

3793

@@ -10,26 +10,26 @@

3794

There are a few functions specific to Python functions.

3795

3796

3797

-.. ctype:: PyFunctionObject

3798

+.. c:type:: PyFunctionObject

3799

3800

The C structure used for functions.

3801

3802

3803

-.. cvar:: PyTypeObject PyFunction_Type

3804

+.. c:var:: PyTypeObject PyFunction_Type

3805

3806

.. index:: single: MethodType (in module types)

3807

3808

- This is an instance of :ctype:`PyTypeObject` and represents the Python function

3809

+ This is an instance of :c:type:`PyTypeObject` and represents the Python function

3810

type. It is exposed to Python programmers as ``types.FunctionType``.

3811

3812

3813

-.. cfunction:: int PyFunction_Check(PyObject *o)

3814

+.. c:function:: int PyFunction_Check(PyObject *o)

3815

3816

- Return true if *o* is a function object (has type :cdata:`PyFunction_Type`).

3817

+ Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).

3818

The parameter must not be *NULL*.

3819

3820

3821

-.. cfunction:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)

3822

+.. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)

3823

3824

Return a new function object associated with the code object *code*. *globals*

3825

must be a dictionary with the global variables accessible to the function.

3826

@@ -38,30 +38,30 @@

3827

object, the argument defaults and closure are set to *NULL*.

3828

3829

3830

-.. cfunction:: PyObject* PyFunction_GetCode(PyObject *op)

3831

+.. c:function:: PyObject* PyFunction_GetCode(PyObject *op)

3832

3833

Return the code object associated with the function object *op*.

3834

3835

3836

-.. cfunction:: PyObject* PyFunction_GetGlobals(PyObject *op)

3837

+.. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op)

3838

3839

Return the globals dictionary associated with the function object *op*.

3840

3841

3842

-.. cfunction:: PyObject* PyFunction_GetModule(PyObject *op)

3843

+.. c:function:: PyObject* PyFunction_GetModule(PyObject *op)

3844

3845

Return the *__module__* attribute of the function object *op*. This is normally

3846

a string containing the module name, but can be set to any other object by

3847

Python code.

3848

3849

3850

-.. cfunction:: PyObject* PyFunction_GetDefaults(PyObject *op)

3851

+.. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)

3852

3853

Return the argument default values of the function object *op*. This can be a

3854

tuple of arguments or *NULL*.

3855

3856

3857

-.. cfunction:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)

3858

+.. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)

3859

3860

Set the argument default values for the function object *op*. *defaults* must be

3861

*Py_None* or a tuple.

3862

@@ -69,13 +69,13 @@

3863

Raises :exc:`SystemError` and returns ``-1`` on failure.

3864

3865

3866

-.. cfunction:: PyObject* PyFunction_GetClosure(PyObject *op)

3867

+.. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)

3868

3869

Return the closure associated with the function object *op*. This can be *NULL*

3870

or a tuple of cell objects.

3871

3872

3873

-.. cfunction:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)

3874

+.. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)

3875

3876

Set the closure associated with the function object *op*. *closure* must be

3877

*Py_None* or a tuple of cell objects.

3878

diff -r 8527427914a2 Doc/c-api/gcsupport.rst

3879

--- a/Doc/c-api/gcsupport.rst

3880

+++ b/Doc/c-api/gcsupport.rst

3881

@@ -30,40 +30,40 @@

3882

3883

Constructors for container types must conform to two rules:

3884

3885

-#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New`

3886

- or :cfunc:`PyObject_GC_NewVar`.

3887

+#. The memory for the object must be allocated using :c:func:`PyObject_GC_New`

3888

+ or :c:func:`PyObject_GC_NewVar`.

3889

3890

#. Once all the fields which may contain references to other containers are

3891

- initialized, it must call :cfunc:`PyObject_GC_Track`.

3892

+ initialized, it must call :c:func:`PyObject_GC_Track`.

3893

3894

3895

-.. cfunction:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)

3896

+.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)

3897

3898

- Analogous to :cfunc:`PyObject_New` but for container objects with the

3899

+ Analogous to :c:func:`PyObject_New` but for container objects with the

3900

:const:`Py_TPFLAGS_HAVE_GC` flag set.

3901

3902

3903

-.. cfunction:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)

3904

+.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)

3905

3906

- Analogous to :cfunc:`PyObject_NewVar` but for container objects with the

3907

+ Analogous to :c:func:`PyObject_NewVar` but for container objects with the

3908

:const:`Py_TPFLAGS_HAVE_GC` flag set.

3909

3910

.. versionchanged:: 2.5

3911

- This function used an :ctype:`int` type for *size*. This might require

3912

+ This function used an :c:type:`int` type for *size*. This might require

3913

changes in your code for properly supporting 64-bit systems.

3914

3915

3916

-.. cfunction:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)

3917

+.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)

3918

3919

- Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the

3920

+ Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the

3921

resized object or *NULL* on failure.

3922

3923

.. versionchanged:: 2.5

3924

- This function used an :ctype:`int` type for *newsize*. This might

3925

+ This function used an :c:type:`int` type for *newsize*. This might

3926

require changes in your code for properly supporting 64-bit systems.

3927

3928

3929

-.. cfunction:: void PyObject_GC_Track(PyObject *op)

3930

+.. c:function:: void PyObject_GC_Track(PyObject *op)

3931

3932

Adds the object *op* to the set of container objects tracked by the

3933

collector. The collector can run at unexpected times so objects must be

3934

@@ -72,44 +72,44 @@

3935

end of the constructor.

3936

3937

3938

-.. cfunction:: void _PyObject_GC_TRACK(PyObject *op)

3939

+.. c:function:: void _PyObject_GC_TRACK(PyObject *op)

3940

3941

- A macro version of :cfunc:`PyObject_GC_Track`. It should not be used for

3942

+ A macro version of :c:func:`PyObject_GC_Track`. It should not be used for

3943

extension modules.

3944

3945

Similarly, the deallocator for the object must conform to a similar pair of

3946

rules:

3947

3948

#. Before fields which refer to other containers are invalidated,

3949

- :cfunc:`PyObject_GC_UnTrack` must be called.

3950

+ :c:func:`PyObject_GC_UnTrack` must be called.

3951

3952

-#. The object's memory must be deallocated using :cfunc:`PyObject_GC_Del`.

3953

+#. The object's memory must be deallocated using :c:func:`PyObject_GC_Del`.

3954

3955

3956

-.. cfunction:: void PyObject_GC_Del(void *op)

3957

+.. c:function:: void PyObject_GC_Del(void *op)

3958

3959

- Releases memory allocated to an object using :cfunc:`PyObject_GC_New` or

3960

- :cfunc:`PyObject_GC_NewVar`.

3961

+ Releases memory allocated to an object using :c:func:`PyObject_GC_New` or

3962

+ :c:func:`PyObject_GC_NewVar`.

3963

3964

3965

-.. cfunction:: void PyObject_GC_UnTrack(void *op)

3966

+.. c:function:: void PyObject_GC_UnTrack(void *op)

3967

3968

Remove the object *op* from the set of container objects tracked by the

3969

- collector. Note that :cfunc:`PyObject_GC_Track` can be called again on

3970

+ collector. Note that :c:func:`PyObject_GC_Track` can be called again on

3971

this object to add it back to the set of tracked objects. The deallocator

3972

(:attr:`tp_dealloc` handler) should call this for the object before any of

3973

the fields used by the :attr:`tp_traverse` handler become invalid.

3974

3975

3976

-.. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op)

3977

+.. c:function:: void _PyObject_GC_UNTRACK(PyObject *op)

3978

3979

- A macro version of :cfunc:`PyObject_GC_UnTrack`. It should not be used for

3980

+ A macro version of :c:func:`PyObject_GC_UnTrack`. It should not be used for

3981

extension modules.

3982

3983

The :attr:`tp_traverse` handler accepts a function parameter of this type:

3984

3985

3986

-.. ctype:: int (*visitproc)(PyObject *object, void *arg)

3987

+.. c:type:: int (*visitproc)(PyObject *object, void *arg)

3988

3989

Type of the visitor function passed to the :attr:`tp_traverse` handler.

3990

The function should be called with an object to traverse as *object* and

3991

@@ -121,7 +121,7 @@

3992

The :attr:`tp_traverse` handler must have the following type:

3993

3994

3995

-.. ctype:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)

3996

+.. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)

3997

3998

Traversal function for a container object. Implementations must call the

3999

*visit* function for each object directly contained by *self*, with the

4000

@@ -130,12 +130,12 @@

4001

object argument. If *visit* returns a non-zero value that value should be

4002

returned immediately.

4003

4004

-To simplify writing :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is

4005

+To simplify writing :attr:`tp_traverse` handlers, a :c:func:`Py_VISIT` macro is

4006

provided. In order to use this macro, the :attr:`tp_traverse` implementation

4007

must name its arguments exactly *visit* and *arg*:

4008

4009

4010

-.. cfunction:: void Py_VISIT(PyObject *o)

4011

+.. c:function:: void Py_VISIT(PyObject *o)

4012

4013

Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns

4014

a non-zero value, then return it. Using this macro, :attr:`tp_traverse`

4015

@@ -151,15 +151,15 @@

4016

4017

.. versionadded:: 2.4

4018

4019

-The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL*

4020

+The :attr:`tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*

4021

if the object is immutable.

4022

4023

4024

-.. ctype:: int (*inquiry)(PyObject *self)

4025

+.. c:type:: int (*inquiry)(PyObject *self)

4026

4027

Drop references that may have created reference cycles. Immutable objects

4028

do not have to define this method since they can never directly create

4029

reference cycles. Note that the object must still be valid after calling

4030

- this method (don't just call :cfunc:`Py_DECREF` on a reference). The

4031

+ this method (don't just call :c:func:`Py_DECREF` on a reference). The

4032

collector will call this method if it detects that this object is involved

4033

in a reference cycle.

4034

diff -r 8527427914a2 Doc/c-api/gen.rst

4035

--- a/Doc/c-api/gen.rst

4036

+++ b/Doc/c-api/gen.rst

4037

@@ -7,31 +7,31 @@

4038

4039

Generator objects are what Python uses to implement generator iterators. They

4040

are normally created by iterating over a function that yields values, rather

4041

-than explicitly calling :cfunc:`PyGen_New`.

4042

+than explicitly calling :c:func:`PyGen_New`.

4043

4044

4045

-.. ctype:: PyGenObject

4046

+.. c:type:: PyGenObject

4047

4048

The C structure used for generator objects.

4049

4050

4051

-.. cvar:: PyTypeObject PyGen_Type

4052

+.. c:var:: PyTypeObject PyGen_Type

4053

4054

The type object corresponding to generator objects

4055

4056

4057

-.. cfunction:: int PyGen_Check(ob)

4058

+.. c:function:: int PyGen_Check(ob)

4059

4060

Return true if *ob* is a generator object; *ob* must not be *NULL*.

4061

4062

4063

-.. cfunction:: int PyGen_CheckExact(ob)

4064

+.. c:function:: int PyGen_CheckExact(ob)

4065

4066

Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not

4067

be *NULL*.

4068

4069

4070

-.. cfunction:: PyObject* PyGen_New(PyFrameObject *frame)

4071

+.. c:function:: PyObject* PyGen_New(PyFrameObject *frame)

4072

4073

Create and return a new generator object based on the *frame* object. A

4074

reference to *frame* is stolen by this function. The parameter must not be

4075

diff -r 8527427914a2 Doc/c-api/import.rst

4076

--- a/Doc/c-api/import.rst

4077

+++ b/Doc/c-api/import.rst

4078

@@ -6,14 +6,14 @@

4079

=================

4080

4081

4082

-.. cfunction:: PyObject* PyImport_ImportModule(const char *name)

4083

+.. c:function:: PyObject* PyImport_ImportModule(const char *name)

4084

4085

.. index::

4086

single: package variable; __all__

4087

single: __all__ (package variable)

4088

single: modules (in module sys)

4089

4090

- This is a simplified interface to :cfunc:`PyImport_ImportModuleEx` below,

4091

+ This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below,

4092

leaving the *globals* and *locals* arguments set to *NULL* and *level* set

4093

to 0. When the *name*

4094

argument contains a dot (when it specifies a submodule of a package), the

4095

@@ -34,20 +34,20 @@

4096

Always uses absolute imports.

4097

4098

4099

-.. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name)

4100

+.. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name)

4101

4102

- This version of :cfunc:`PyImport_ImportModule` does not block. It's intended

4103

+ This version of :c:func:`PyImport_ImportModule` does not block. It's intended

4104

to be used in C functions that import other modules to execute a function.

4105

The import may block if another thread holds the import lock. The function

4106

- :cfunc:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch

4107

- the module from sys.modules and falls back to :cfunc:`PyImport_ImportModule`

4108

+ :c:func:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch

4109

+ the module from sys.modules and falls back to :c:func:`PyImport_ImportModule`

4110

unless the lock is held, in which case the function will raise an

4111

:exc:`ImportError`.

4112

4113

.. versionadded:: 2.6

4114

4115

4116

-.. cfunction:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)

4117

+.. c:function:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)

4118

4119

.. index:: builtin: __import__

4120

4121

@@ -65,11 +65,11 @@

4122

Failing imports remove incomplete module objects.

4123

4124

.. versionchanged:: 2.6

4125

- The function is an alias for :cfunc:`PyImport_ImportModuleLevel` with

4126

+ The function is an alias for :c:func:`PyImport_ImportModuleLevel` with

4127

-1 as level, meaning relative import.

4128

4129

4130

-.. cfunction:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

4131

+.. c:function:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

4132

4133

Import a module. This is best described by referring to the built-in Python

4134

function :func:`__import__`, as the standard :func:`__import__` function calls

4135

@@ -83,7 +83,7 @@

4136

.. versionadded:: 2.5

4137

4138

4139

-.. cfunction:: PyObject* PyImport_Import(PyObject *name)

4140

+.. c:function:: PyObject* PyImport_Import(PyObject *name)

4141

4142

.. index::

4143

module: rexec

4144

@@ -98,7 +98,7 @@

4145

Always uses absolute imports.

4146

4147

4148

-.. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m)

4149

+.. c:function:: PyObject* PyImport_ReloadModule(PyObject *m)

4150

4151

.. index:: builtin: reload

4152

4153

@@ -108,7 +108,7 @@

4154

with an exception set on failure (the module still exists in this case).

4155

4156

4157

-.. cfunction:: PyObject* PyImport_AddModule(const char *name)

4158

+.. c:function:: PyObject* PyImport_AddModule(const char *name)

4159

4160

Return the module object corresponding to a module name. The *name* argument

4161

may be of the form ``package.module``. First check the modules dictionary if

4162

@@ -118,12 +118,12 @@

4163

.. note::

4164

4165

This function does not load or import the module; if the module wasn't already

4166

- loaded, you will get an empty module object. Use :cfunc:`PyImport_ImportModule`

4167

+ loaded, you will get an empty module object. Use :c:func:`PyImport_ImportModule`

4168

or one of its variants to import a module. Package structures implied by a

4169

dotted name for *name* are not created if not already present.

4170

4171

4172

-.. cfunction:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)

4173

+.. c:function:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)

4174

4175

.. index:: builtin: compile

4176

4177

@@ -133,16 +133,16 @@

4178

or *NULL* with an exception set if an error occurred. Before Python 2.4, the

4179

module could still be created in error cases. Starting with Python 2.4, *name*

4180

is removed from :attr:`sys.modules` in error cases, and even if *name* was already

4181

- in :attr:`sys.modules` on entry to :cfunc:`PyImport_ExecCodeModule`. Leaving

4182

+ in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving

4183

incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of

4184

such modules have no way to know that the module object is an unknown (and

4185

probably damaged with respect to the module author's intents) state.

4186

4187

The module's :attr:`__file__` attribute will be set to the code object's

4188

- :cmember:`co_filename`.

4189

+ :c:member:`co_filename`.

4190

4191

This function will reload the module if it was already imported. See

4192

- :cfunc:`PyImport_ReloadModule` for the intended way to reload a module.

4193

+ :c:func:`PyImport_ReloadModule` for the intended way to reload a module.

4194

4195

If *name* points to a dotted name of the form ``package.module``, any package

4196

structures not already created will still not be created.

4197

@@ -151,26 +151,26 @@

4198

*name* is removed from :attr:`sys.modules` in error cases.

4199

4200

4201

-.. cfunction:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)

4202

+.. c:function:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)

4203

4204

- Like :cfunc:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of

4205

+ Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of

4206

the module object is set to *pathname* if it is non-``NULL``.

4207

4208

4209

-.. cfunction:: long PyImport_GetMagicNumber()

4210

+.. c:function:: long PyImport_GetMagicNumber()

4211

4212

Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and

4213

:file:`.pyo` files). The magic number should be present in the first four bytes

4214

of the bytecode file, in little-endian byte order.

4215

4216

4217

-.. cfunction:: PyObject* PyImport_GetModuleDict()

4218

+.. c:function:: PyObject* PyImport_GetModuleDict()

4219

4220

Return the dictionary used for the module administration (a.k.a.

4221

``sys.modules``). Note that this is a per-interpreter variable.

4222

4223

4224

-.. cfunction:: PyObject* PyImport_GetImporter(PyObject *path)

4225

+.. c:function:: PyObject* PyImport_GetImporter(PyObject *path)

4226

4227

Return an importer object for a :data:`sys.path`/:attr:`pkg.__path__` item

4228

*path*, possibly by fetching it from the :data:`sys.path_importer_cache`

4229

@@ -183,41 +183,41 @@

4230

.. versionadded:: 2.6

4231

4232

4233

-.. cfunction:: void _PyImport_Init()

4234

+.. c:function:: void _PyImport_Init()

4235

4236

Initialize the import mechanism. For internal use only.

4237

4238

4239

-.. cfunction:: void PyImport_Cleanup()

4240

+.. c:function:: void PyImport_Cleanup()

4241

4242

Empty the module table. For internal use only.

4243

4244

4245

-.. cfunction:: void _PyImport_Fini()

4246

+.. c:function:: void _PyImport_Fini()

4247

4248

Finalize the import mechanism. For internal use only.

4249

4250

4251

-.. cfunction:: PyObject* _PyImport_FindExtension(char *, char *)

4252

+.. c:function:: PyObject* _PyImport_FindExtension(char *, char *)

4253

4254

For internal use only.

4255

4256

4257

-.. cfunction:: PyObject* _PyImport_FixupExtension(char *, char *)

4258

+.. c:function:: PyObject* _PyImport_FixupExtension(char *, char *)

4259

4260

For internal use only.

4261

4262

4263

-.. cfunction:: int PyImport_ImportFrozenModule(char *name)

4264

+.. c:function:: int PyImport_ImportFrozenModule(char *name)

4265

4266

Load a frozen module named *name*. Return ``1`` for success, ``0`` if the

4267

module is not found, and ``-1`` with an exception set if the initialization

4268

failed. To access the imported module on a successful load, use

4269

- :cfunc:`PyImport_ImportModule`. (Note the misnomer --- this function would

4270

+ :c:func:`PyImport_ImportModule`. (Note the misnomer --- this function would

4271

reload the module if it was already imported.)

4272

4273

4274

-.. ctype:: struct _frozen

4275

+.. c:type:: struct _frozen

4276

4277

.. index:: single: freeze utility

4278

4279

@@ -233,30 +233,30 @@

4280

};

4281

4282

4283

-.. cvar:: struct _frozen* PyImport_FrozenModules

4284

+.. c:var:: struct _frozen* PyImport_FrozenModules

4285

4286

- This pointer is initialized to point to an array of :ctype:`struct _frozen`

4287

+ This pointer is initialized to point to an array of :c:type:`struct _frozen`

4288

records, terminated by one whose members are all *NULL* or zero. When a frozen

4289

module is imported, it is searched in this table. Third-party code could play

4290

tricks with this to provide a dynamically created collection of frozen modules.

4291

4292

4293

-.. cfunction:: int PyImport_AppendInittab(const char *name, void (*initfunc)(void))

4294

+.. c:function:: int PyImport_AppendInittab(const char *name, void (*initfunc)(void))

4295

4296

Add a single module to the existing table of built-in modules. This is a

4297

- convenience wrapper around :cfunc:`PyImport_ExtendInittab`, returning ``-1`` if

4298

+ convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning ``-1`` if

4299

the table could not be extended. The new module can be imported by the name

4300

*name*, and uses the function *initfunc* as the initialization function called

4301

on the first attempted import. This should be called before

4302

- :cfunc:`Py_Initialize`.

4303

+ :c:func:`Py_Initialize`.

4304

4305

4306

-.. ctype:: struct _inittab

4307

+.. c:type:: struct _inittab

4308

4309

Structure describing a single entry in the list of built-in modules. Each of

4310

these structures gives the name and initialization function for a module built

4311

into the interpreter. Programs which embed Python may use an array of these

4312

- structures in conjunction with :cfunc:`PyImport_ExtendInittab` to provide

4313

+ structures in conjunction with :c:func:`PyImport_ExtendInittab` to provide

4314

additional built-in modules. The structure is defined in

4315

:file:`Include/import.h` as::

4316

4317

@@ -266,11 +266,11 @@

4318

};

4319

4320

4321

-.. cfunction:: int PyImport_ExtendInittab(struct _inittab *newtab)

4322

+.. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab)

4323

4324

Add a collection of modules to the table of built-in modules. The *newtab*

4325

array must end with a sentinel entry which contains *NULL* for the :attr:`name`

4326

field; failure to provide the sentinel value can result in a memory fault.

4327

Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to

4328

extend the internal table. In the event of failure, no modules are added to the

4329

- internal table. This should be called before :cfunc:`Py_Initialize`.

4330

+ internal table. This should be called before :c:func:`Py_Initialize`.

4331

diff -r 8527427914a2 Doc/c-api/init.rst

4332

--- a/Doc/c-api/init.rst

4333

+++ b/Doc/c-api/init.rst

4334

@@ -12,7 +12,7 @@

4335

===========================================

4336

4337

4338

-.. cfunction:: void Py_Initialize()

4339

+.. c:function:: void Py_Initialize()

4340

4341

.. index::

4342

single: Py_SetProgramName()

4343

@@ -31,40 +31,40 @@

4344

4345

Initialize the Python interpreter. In an application embedding Python, this

4346

should be called before using any other Python/C API functions; with the

4347

- exception of :cfunc:`Py_SetProgramName`, :cfunc:`PyEval_InitThreads`,

4348

- :cfunc:`PyEval_ReleaseLock`, and :cfunc:`PyEval_AcquireLock`. This initializes

4349

+ exception of :c:func:`Py_SetProgramName`, :c:func:`Py_SetPythonHome`, :c:func:`PyEval_InitThreads`,

4350

+ :c:func:`PyEval_ReleaseLock`, and :c:func:`PyEval_AcquireLock`. This initializes

4351

the table of loaded modules (``sys.modules``), and creates the fundamental

4352

modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. It also initializes

4353

the module search path (``sys.path``). It does not set ``sys.argv``; use

4354

- :cfunc:`PySys_SetArgvEx` for that. This is a no-op when called for a second time

4355

- (without calling :cfunc:`Py_Finalize` first). There is no return value; it is a

4356

+ :c:func:`PySys_SetArgvEx` for that. This is a no-op when called for a second time

4357

+ (without calling :c:func:`Py_Finalize` first). There is no return value; it is a

4358

fatal error if the initialization fails.

4359

4360

4361

-.. cfunction:: void Py_InitializeEx(int initsigs)

4362

+.. c:function:: void Py_InitializeEx(int initsigs)

4363

4364

- This function works like :cfunc:`Py_Initialize` if *initsigs* is 1. If

4365

+ This function works like :c:func:`Py_Initialize` if *initsigs* is 1. If

4366

*initsigs* is 0, it skips initialization registration of signal handlers, which

4367

might be useful when Python is embedded.

4368

4369

.. versionadded:: 2.4

4370

4371

4372

-.. cfunction:: int Py_IsInitialized()

4373

+.. c:function:: int Py_IsInitialized()

4374

4375

Return true (nonzero) when the Python interpreter has been initialized, false

4376

- (zero) if not. After :cfunc:`Py_Finalize` is called, this returns false until

4377

- :cfunc:`Py_Initialize` is called again.

4378

+ (zero) if not. After :c:func:`Py_Finalize` is called, this returns false until

4379

+ :c:func:`Py_Initialize` is called again.

4380

4381

4382

-.. cfunction:: void Py_Finalize()

4383

+.. c:function:: void Py_Finalize()

4384

4385

- Undo all initializations made by :cfunc:`Py_Initialize` and subsequent use of

4386

+ Undo all initializations made by :c:func:`Py_Initialize` and subsequent use of

4387

Python/C API functions, and destroy all sub-interpreters (see

4388

- :cfunc:`Py_NewInterpreter` below) that were created and not yet destroyed since

4389

- the last call to :cfunc:`Py_Initialize`. Ideally, this frees all memory

4390

+ :c:func:`Py_NewInterpreter` below) that were created and not yet destroyed since

4391

+ the last call to :c:func:`Py_Initialize`. Ideally, this frees all memory

4392

allocated by the Python interpreter. This is a no-op when called for a second

4393

- time (without calling :cfunc:`Py_Initialize` again first). There is no return

4394

+ time (without calling :c:func:`Py_Initialize` again first). There is no return

4395

value; errors during finalization are ignored.

4396

4397

This function is provided for a number of reasons. An embedding application

4398

@@ -83,25 +83,25 @@

4399

please report it). Memory tied up in circular references between objects is not

4400

freed. Some memory allocated by extension modules may not be freed. Some

4401

extensions may not work properly if their initialization routine is called more

4402

- than once; this can happen if an application calls :cfunc:`Py_Initialize` and

4403

- :cfunc:`Py_Finalize` more than once.

4404

+ than once; this can happen if an application calls :c:func:`Py_Initialize` and

4405

+ :c:func:`Py_Finalize` more than once.

4406

4407

4408

Process-wide parameters

4409

=======================

4410

4411

4412

-.. cfunction:: void Py_SetProgramName(char *name)

4413

+.. c:function:: void Py_SetProgramName(char *name)

4414

4415

.. index::

4416

single: Py_Initialize()

4417

single: main()

4418

single: Py_GetPath()

4419

4420

- This function should be called before :cfunc:`Py_Initialize` is called for

4421

+ This function should be called before :c:func:`Py_Initialize` is called for

4422

the first time, if it is called at all. It tells the interpreter the value

4423

- of the ``argv[0]`` argument to the :cfunc:`main` function of the program.

4424

- This is used by :cfunc:`Py_GetPath` and some other functions below to find

4425

+ of the ``argv[0]`` argument to the :c:func:`main` function of the program.

4426

+ This is used by :c:func:`Py_GetPath` and some other functions below to find

4427

the Python run-time libraries relative to the interpreter executable. The

4428

default value is ``'python'``. The argument should point to a

4429

zero-terminated character string in static storage whose contents will not

4430

@@ -109,37 +109,37 @@

4431

interpreter will change the contents of this storage.

4432

4433

4434

-.. cfunction:: char* Py_GetProgramName()

4435

+.. c:function:: char* Py_GetProgramName()

4436

4437

.. index:: single: Py_SetProgramName()

4438

4439

- Return the program name set with :cfunc:`Py_SetProgramName`, or the default.

4440

+ Return the program name set with :c:func:`Py_SetProgramName`, or the default.

4441

The returned string points into static storage; the caller should not modify its

4442

value.

4443

4444

4445

-.. cfunction:: char* Py_GetPrefix()

4446

+.. c:function:: char* Py_GetPrefix()

4447

4448

Return the *prefix* for installed platform-independent files. This is derived

4449

through a number of complicated rules from the program name set with

4450

- :cfunc:`Py_SetProgramName` and some environment variables; for example, if the

4451

+ :c:func:`Py_SetProgramName` and some environment variables; for example, if the

4452

program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The

4453

returned string points into static storage; the caller should not modify its

4454

value. This corresponds to the :makevar:`prefix` variable in the top-level

4455

- :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure`

4456

+ :file:`Makefile` and the ``--prefix`` argument to the :program:`configure`

4457

script at build time. The value is available to Python code as ``sys.prefix``.

4458

It is only useful on Unix. See also the next function.

4459

4460

4461

-.. cfunction:: char* Py_GetExecPrefix()

4462

+.. c:function:: char* Py_GetExecPrefix()

4463

4464

Return the *exec-prefix* for installed platform-*dependent* files. This is

4465

derived through a number of complicated rules from the program name set with

4466

- :cfunc:`Py_SetProgramName` and some environment variables; for example, if the

4467

+ :c:func:`Py_SetProgramName` and some environment variables; for example, if the

4468

program name is ``'/usr/local/bin/python'``, the exec-prefix is

4469

``'/usr/local'``. The returned string points into static storage; the caller

4470

should not modify its value. This corresponds to the :makevar:`exec_prefix`

4471

- variable in the top-level :file:`Makefile` and the :option:`--exec-prefix`

4472

+ variable in the top-level :file:`Makefile` and the ``--exec-prefix``

4473

argument to the :program:`configure` script at build time. The value is

4474

available to Python code as ``sys.exec_prefix``. It is only useful on Unix.

4475

4476

@@ -166,7 +166,7 @@

4477

platform.

4478

4479

4480

-.. cfunction:: char* Py_GetProgramFullPath()

4481

+.. c:function:: char* Py_GetProgramFullPath()

4482

4483

.. index::

4484

single: Py_SetProgramName()

4485

@@ -174,19 +174,19 @@

4486

4487

Return the full program name of the Python executable; this is computed as a

4488

side-effect of deriving the default module search path from the program name

4489

- (set by :cfunc:`Py_SetProgramName` above). The returned string points into

4490

+ (set by :c:func:`Py_SetProgramName` above). The returned string points into

4491

static storage; the caller should not modify its value. The value is available

4492

to Python code as ``sys.executable``.

4493

4494

4495

-.. cfunction:: char* Py_GetPath()

4496

+.. c:function:: char* Py_GetPath()

4497

4498

.. index::

4499

triple: module; search; path

4500

single: path (in module sys)

4501

4502

Return the default module search path; this is computed from the program name

4503

- (set by :cfunc:`Py_SetProgramName` above) and some environment variables.

4504

+ (set by :c:func:`Py_SetProgramName` above) and some environment variables.

4505

The returned string consists of a series of directory names separated by a

4506

platform dependent delimiter character. The delimiter character is ``':'``

4507

on Unix and Mac OS X, ``';'`` on Windows. The returned string points into

4508

@@ -198,7 +198,7 @@

4509

.. XXX should give the exact rules

4510

4511

4512

-.. cfunction:: const char* Py_GetVersion()

4513

+.. c:function:: const char* Py_GetVersion()

4514

4515

Return the version of this Python interpreter. This is a string that looks

4516

something like ::

4517

@@ -213,7 +213,7 @@

4518

modify its value. The value is available to Python code as ``sys.version``.

4519

4520

4521

-.. cfunction:: const char* Py_GetPlatform()

4522

+.. c:function:: const char* Py_GetPlatform()

4523

4524

.. index:: single: platform (in module sys)

4525

4526

@@ -226,7 +226,7 @@

4527

to Python code as ``sys.platform``.

4528

4529

4530

-.. cfunction:: const char* Py_GetCopyright()

4531

+.. c:function:: const char* Py_GetCopyright()

4532

4533

Return the official copyright string for the current Python version, for example

4534

4535

@@ -238,7 +238,7 @@

4536

value. The value is available to Python code as ``sys.copyright``.

4537

4538

4539

-.. cfunction:: const char* Py_GetCompiler()

4540

+.. c:function:: const char* Py_GetCompiler()

4541

4542

Return an indication of the compiler used to build the current Python version,

4543

in square brackets, for example::

4544

@@ -252,7 +252,7 @@

4545

``sys.version``.

4546

4547

4548

-.. cfunction:: const char* Py_GetBuildInfo()

4549

+.. c:function:: const char* Py_GetBuildInfo()

4550

4551

Return information about the sequence number and build date and time of the

4552

current Python interpreter instance, for example ::

4553

@@ -266,7 +266,7 @@

4554

``sys.version``.

4555

4556

4557

-.. cfunction:: void PySys_SetArgvEx(int argc, char **argv, int updatepath)

4558

+.. c:function:: void PySys_SetArgvEx(int argc, char **argv, int updatepath)

4559

4560

.. index::

4561

single: main()

4562

@@ -274,12 +274,12 @@

4563

single: argv (in module sys)

4564

4565

Set :data:`sys.argv` based on *argc* and *argv*. These parameters are

4566

- similar to those passed to the program's :cfunc:`main` function with the

4567

+ similar to those passed to the program's :c:func:`main` function with the

4568

difference that the first entry should refer to the script file to be

4569

executed rather than the executable hosting the Python interpreter. If there

4570

isn't a script that will be run, the first entry in *argv* can be an empty

4571

string. If this function fails to initialize :data:`sys.argv`, a fatal

4572

- condition is signalled using :cfunc:`Py_FatalError`.

4573

+ condition is signalled using :c:func:`Py_FatalError`.

4574

4575

If *updatepath* is zero, this is all the function does. If *updatepath*

4576

is non-zero, the function also modifies :data:`sys.path` according to the

4577

@@ -301,7 +301,7 @@

4578

4579

On versions before 2.6.6, you can achieve the same effect by manually

4580

popping the first :data:`sys.path` element after having called

4581

- :cfunc:`PySys_SetArgv`, for example using::

4582

+ :c:func:`PySys_SetArgv`, for example using::

4583

4584

PyRun_SimpleString("import sys; sys.path.pop(0)\n");

4585

4586

@@ -311,12 +311,12 @@

4587

check w/ Guido.

4588

4589

4590

-.. cfunction:: void PySys_SetArgv(int argc, char **argv)

4591

+.. c:function:: void PySys_SetArgv(int argc, char **argv)

4592

4593

- This function works like :cfunc:`PySys_SetArgvEx` with *updatepath* set to 1.

4594

+ This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to 1.

4595

4596

4597

-.. cfunction:: void Py_SetPythonHome(char *home)

4598

+.. c:function:: void Py_SetPythonHome(char *home)

4599

4600

Set the default "home" directory, that is, the location of the standard

4601

Python libraries. See :envvar:`PYTHONHOME` for the meaning of the

4602

@@ -328,10 +328,10 @@

4603

this storage.

4604

4605

4606

-.. cfunction:: char* Py_GetPythonHome()

4607

+.. c:function:: char* Py_GetPythonHome()

4608

4609

Return the default "home", that is, the value set by a previous call to

4610

- :cfunc:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`

4611

+ :c:func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`

4612

environment variable if it is set.

4613

4614

4615

@@ -368,9 +368,9 @@

4616

single: PyThreadState

4617

4618

The Python interpreter keeps some thread-specific bookkeeping information

4619

-inside a data structure called :ctype:`PyThreadState`. There's also one

4620

-global variable pointing to the current :ctype:`PyThreadState`: it can

4621

-be retrieved using :cfunc:`PyThreadState_Get`.

4622

+inside a data structure called :c:type:`PyThreadState`. There's also one

4623

+global variable pointing to the current :c:type:`PyThreadState`: it can

4624

+be retrieved using :c:func:`PyThreadState_Get`.

4625

4626

Releasing the GIL from extension code

4627

-------------------------------------

4628

@@ -394,8 +394,8 @@

4629

single: Py_BEGIN_ALLOW_THREADS

4630

single: Py_END_ALLOW_THREADS

4631

4632

-The :cmacro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a

4633

-hidden local variable; the :cmacro:`Py_END_ALLOW_THREADS` macro closes the

4634

+The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a

4635

+hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the

4636

block. These two macros are still available when Python is compiled without

4637

thread support (they simply have an empty expansion).

4638

4639

@@ -445,7 +445,7 @@

4640

API. When you are done, you should reset the thread state pointer, release

4641

the GIL, and finally free the thread state data structure.

4642

4643

-The :cfunc:`PyGILState_Ensure` and :cfunc:`PyGILState_Release` functions do

4644

+The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions do

4645

all of the above automatically. The typical idiom for calling into Python

4646

from a C thread is::

4647

4648

@@ -459,14 +459,14 @@

4649

/* Release the thread. No Python API allowed beyond this point. */

4650

PyGILState_Release(gstate);

4651

4652

-Note that the :cfunc:`PyGILState_\*` functions assume there is only one global

4653

-interpreter (created automatically by :cfunc:`Py_Initialize`). Python

4654

+Note that the :c:func:`PyGILState_\*` functions assume there is only one global

4655

+interpreter (created automatically by :c:func:`Py_Initialize`). Python

4656

supports the creation of additional interpreters (using

4657

-:cfunc:`Py_NewInterpreter`), but mixing multiple interpreters and the

4658

-:cfunc:`PyGILState_\*` API is unsupported.

4659

+:c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the

4660

+:c:func:`PyGILState_\*` API is unsupported.

4661

4662

Another important thing to note about threads is their behaviour in the face

4663

-of the C :cfunc:`fork` call. On most systems with :cfunc:`fork`, after a

4664

+of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a

4665

process forks only the thread that issued the fork will exist. That also

4666

means any locks held by other threads will never be released. Python solves

4667

this for :func:`os.fork` by acquiring the locks it uses internally before

4668

@@ -474,12 +474,12 @@

4669

:ref:`lock-objects` in the child. When extending or embedding Python, there

4670

is no way to inform Python of additional (non-Python) locks that need to be

4671

acquired before or reset after a fork. OS facilities such as

4672

-:cfunc:`pthread_atfork` would need to be used to accomplish the same thing.

4673

-Additionally, when extending or embedding Python, calling :cfunc:`fork`

4674

+:c:func:`pthread_atfork` would need to be used to accomplish the same thing.

4675

+Additionally, when extending or embedding Python, calling :c:func:`fork`

4676

directly rather than through :func:`os.fork` (and returning to or calling

4677

into Python) may result in a deadlock by one of Python's internal locks

4678

being held by a thread that is defunct after the fork.

4679

-:cfunc:`PyOS_AfterFork` tries to reset the necessary locks, but is not

4680

+:c:func:`PyOS_AfterFork` tries to reset the necessary locks, but is not

4681

always able to.

4682

4683

4684

@@ -489,7 +489,7 @@

4685

These are the most commonly used types and functions when writing C extension

4686

code, or when embedding the Python interpreter:

4687

4688

-.. ctype:: PyInterpreterState

4689

+.. c:type:: PyInterpreterState

4690

4691

This data structure represents the state shared by a number of cooperating

4692

threads. Threads belonging to the same interpreter share their module

4693

@@ -502,14 +502,14 @@

4694

interpreter they belong.

4695

4696

4697

-.. ctype:: PyThreadState

4698

+.. c:type:: PyThreadState

4699

4700

This data structure represents the state of a single thread. The only public

4701

- data member is :ctype:`PyInterpreterState \*`:attr:`interp`, which points to

4702

+ data member is :c:type:`PyInterpreterState \*`:attr:`interp`, which points to

4703

this thread's interpreter state.

4704

4705

4706

-.. cfunction:: void PyEval_InitThreads()

4707

+.. c:function:: void PyEval_InitThreads()

4708

4709

.. index::

4710

single: PyEval_ReleaseLock()

4711

@@ -519,14 +519,14 @@

4712

4713

Initialize and acquire the global interpreter lock. It should be called in the

4714

main thread before creating a second thread or engaging in any other thread

4715

- operations such as :cfunc:`PyEval_ReleaseLock` or

4716

+ operations such as :c:func:`PyEval_ReleaseLock` or

4717

``PyEval_ReleaseThread(tstate)``. It is not needed before calling

4718

- :cfunc:`PyEval_SaveThread` or :cfunc:`PyEval_RestoreThread`.

4719

+ :c:func:`PyEval_SaveThread` or :c:func:`PyEval_RestoreThread`.

4720

4721

.. index:: single: Py_Initialize()

4722

4723

This is a no-op when called for a second time. It is safe to call this function

4724

- before calling :cfunc:`Py_Initialize`.

4725

+ before calling :c:func:`Py_Initialize`.

4726

4727

.. index:: module: thread

4728

4729

@@ -539,7 +539,7 @@

4730

when this function initializes the global interpreter lock, it also acquires

4731

it. Before the Python :mod:`_thread` module creates a new thread, knowing

4732

that either it has the lock or the lock hasn't been created yet, it calls

4733

- :cfunc:`PyEval_InitThreads`. When this call returns, it is guaranteed that

4734

+ :c:func:`PyEval_InitThreads`. When this call returns, it is guaranteed that

4735

the lock has been created and that the calling thread has acquired it.

4736

4737

It is **not** safe to call this function when it is unknown which thread (if

4738

@@ -548,9 +548,9 @@

4739

This function is not available when thread support is disabled at compile time.

4740

4741

4742

-.. cfunction:: int PyEval_ThreadsInitialized()

4743

+.. c:function:: int PyEval_ThreadsInitialized()

4744

4745

- Returns a non-zero value if :cfunc:`PyEval_InitThreads` has been called. This

4746

+ Returns a non-zero value if :c:func:`PyEval_InitThreads` has been called. This

4747

function can be called without holding the GIL, and therefore can be used to

4748

avoid calls to the locking API when running single-threaded. This function is

4749

not available when thread support is disabled at compile time.

4750

@@ -558,7 +558,7 @@

4751

.. versionadded:: 2.4

4752

4753

4754

-.. cfunction:: PyThreadState* PyEval_SaveThread()

4755

+.. c:function:: PyThreadState* PyEval_SaveThread()

4756

4757

Release the global interpreter lock (if it has been created and thread

4758

support is enabled) and reset the thread state to *NULL*, returning the

4759

@@ -567,7 +567,7 @@

4760

when thread support is disabled at compile time.)

4761

4762

4763

-.. cfunction:: void PyEval_RestoreThread(PyThreadState *tstate)

4764

+.. c:function:: void PyEval_RestoreThread(PyThreadState *tstate)

4765

4766

Acquire the global interpreter lock (if it has been created and thread

4767

support is enabled) and set the thread state to *tstate*, which must not be

4768

@@ -576,23 +576,23 @@

4769

when thread support is disabled at compile time.)

4770

4771

4772

-.. cfunction:: PyThreadState* PyThreadState_Get()

4773

+.. c:function:: PyThreadState* PyThreadState_Get()

4774

4775

Return the current thread state. The global interpreter lock must be held.

4776

When the current thread state is *NULL*, this issues a fatal error (so that

4777

the caller needn't check for *NULL*).

4778

4779

4780

-.. cfunction:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)

4781

+.. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)

4782

4783

Swap the current thread state with the thread state given by the argument

4784

*tstate*, which may be *NULL*. The global interpreter lock must be held

4785

and is not released.

4786

4787

4788

-.. cfunction:: void PyEval_ReInitThreads()

4789

+.. c:function:: void PyEval_ReInitThreads()

4790

4791

- This function is called from :cfunc:`PyOS_AfterFork` to ensure that newly

4792

+ This function is called from :c:func:`PyOS_AfterFork` to ensure that newly

4793

created child processes don't hold locks referring to threads which

4794

are not running in the child process.

4795

4796

@@ -600,24 +600,24 @@

4797

The following functions use thread-local storage, and are not compatible

4798

with sub-interpreters:

4799

4800

-.. cfunction:: PyGILState_STATE PyGILState_Ensure()

4801

+.. c:function:: PyGILState_STATE PyGILState_Ensure()

4802

4803

Ensure that the current thread is ready to call the Python C API regardless

4804

of the current state of Python, or of the global interpreter lock. This may

4805

be called as many times as desired by a thread as long as each call is

4806

- matched with a call to :cfunc:`PyGILState_Release`. In general, other

4807

- thread-related APIs may be used between :cfunc:`PyGILState_Ensure` and

4808

- :cfunc:`PyGILState_Release` calls as long as the thread state is restored to

4809

+ matched with a call to :c:func:`PyGILState_Release`. In general, other

4810

+ thread-related APIs may be used between :c:func:`PyGILState_Ensure` and

4811

+ :c:func:`PyGILState_Release` calls as long as the thread state is restored to

4812

its previous state before the Release(). For example, normal usage of the

4813

- :cmacro:`Py_BEGIN_ALLOW_THREADS` and :cmacro:`Py_END_ALLOW_THREADS` macros is

4814

+ :c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros is

4815

acceptable.

4816

4817

The return value is an opaque "handle" to the thread state when

4818

- :cfunc:`PyGILState_Ensure` was called, and must be passed to

4819

- :cfunc:`PyGILState_Release` to ensure Python is left in the same state. Even

4820

+ :c:func:`PyGILState_Ensure` was called, and must be passed to

4821

+ :c:func:`PyGILState_Release` to ensure Python is left in the same state. Even

4822

though recursive calls are allowed, these handles *cannot* be shared - each

4823

- unique call to :cfunc:`PyGILState_Ensure` must save the handle for its call

4824

- to :cfunc:`PyGILState_Release`.

4825

+ unique call to :c:func:`PyGILState_Ensure` must save the handle for its call

4826

+ to :c:func:`PyGILState_Release`.

4827

4828

When the function returns, the current thread will hold the GIL and be able

4829

to call arbitrary Python code. Failure is a fatal error.

4830

@@ -625,15 +625,25 @@

4831

.. versionadded:: 2.3

4832

4833

4834

-.. cfunction:: void PyGILState_Release(PyGILState_STATE)

4835

+.. c:function:: void PyGILState_Release(PyGILState_STATE)

4836

4837

Release any resources previously acquired. After this call, Python's state will

4838

- be the same as it was prior to the corresponding :cfunc:`PyGILState_Ensure` call

4839

+ be the same as it was prior to the corresponding :c:func:`PyGILState_Ensure` call

4840

(but generally this state will be unknown to the caller, hence the use of the

4841

GILState API).

4842

4843

- Every call to :cfunc:`PyGILState_Ensure` must be matched by a call to

4844

- :cfunc:`PyGILState_Release` on the same thread.

4845

+ Every call to :c:func:`PyGILState_Ensure` must be matched by a call to

4846

+ :c:func:`PyGILState_Release` on the same thread.

4847

+

4848

+ .. versionadded:: 2.3

4849

+

4850

+

4851

+.. c:function:: PyThreadState PyGILState_GetThisThreadState()

4852

+

4853

+ Get the current thread state for this thread. May return ``NULL`` if no

4854

+ GILState API has been used on the current thread. Note that the main thread

4855

+ always has such a thread-state, even if no auto-thread-state call has been

4856

+ made on the main thread. This is mainly a helper/diagnostic function.

4857

4858

.. versionadded:: 2.3

4859

4860

@@ -642,33 +652,33 @@

4861

example usage in the Python source distribution.

4862

4863

4864

-.. cmacro:: Py_BEGIN_ALLOW_THREADS

4865

+.. c:macro:: Py_BEGIN_ALLOW_THREADS

4866

4867

This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``.

4868

Note that it contains an opening brace; it must be matched with a following

4869

- :cmacro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this

4870

+ :c:macro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this

4871

macro. It is a no-op when thread support is disabled at compile time.

4872

4873

4874

-.. cmacro:: Py_END_ALLOW_THREADS

4875

+.. c:macro:: Py_END_ALLOW_THREADS

4876

4877

This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains

4878

a closing brace; it must be matched with an earlier

4879

- :cmacro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of

4880

+ :c:macro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of

4881

this macro. It is a no-op when thread support is disabled at compile time.

4882

4883

4884

-.. cmacro:: Py_BLOCK_THREADS

4885

+.. c:macro:: Py_BLOCK_THREADS

4886

4887

This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to

4888

- :cmacro:`Py_END_ALLOW_THREADS` without the closing brace. It is a no-op when

4889

+ :c:macro:`Py_END_ALLOW_THREADS` without the closing brace. It is a no-op when

4890

thread support is disabled at compile time.

4891

4892

4893

-.. cmacro:: Py_UNBLOCK_THREADS

4894

+.. c:macro:: Py_UNBLOCK_THREADS

4895

4896

This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to

4897

- :cmacro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable

4898

+ :c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable

4899

declaration. It is a no-op when thread support is disabled at compile time.

4900

4901

4902

@@ -680,47 +690,47 @@

4903

been created.

4904

4905

4906

-.. cfunction:: PyInterpreterState* PyInterpreterState_New()

4907

+.. c:function:: PyInterpreterState* PyInterpreterState_New()

4908

4909

Create a new interpreter state object. The global interpreter lock need not

4910

be held, but may be held if it is necessary to serialize calls to this

4911

function.

4912

4913

4914

-.. cfunction:: void PyInterpreterState_Clear(PyInterpreterState *interp)

4915

+.. c:function:: void PyInterpreterState_Clear(PyInterpreterState *interp)

4916

4917

Reset all information in an interpreter state object. The global interpreter

4918

lock must be held.

4919

4920

4921

-.. cfunction:: void PyInterpreterState_Delete(PyInterpreterState *interp)

4922

+.. c:function:: void PyInterpreterState_Delete(PyInterpreterState *interp)

4923

4924

Destroy an interpreter state object. The global interpreter lock need not be

4925

held. The interpreter state must have been reset with a previous call to

4926

- :cfunc:`PyInterpreterState_Clear`.

4927

+ :c:func:`PyInterpreterState_Clear`.

4928

4929

4930

-.. cfunction:: PyThreadState* PyThreadState_New(PyInterpreterState *interp)

4931

+.. c:function:: PyThreadState* PyThreadState_New(PyInterpreterState *interp)

4932

4933

Create a new thread state object belonging to the given interpreter object.

4934

The global interpreter lock need not be held, but may be held if it is

4935

necessary to serialize calls to this function.

4936

4937

4938

-.. cfunction:: void PyThreadState_Clear(PyThreadState *tstate)

4939

+.. c:function:: void PyThreadState_Clear(PyThreadState *tstate)

4940

4941

Reset all information in a thread state object. The global interpreter lock

4942

must be held.

4943

4944

4945

-.. cfunction:: void PyThreadState_Delete(PyThreadState *tstate)

4946

+.. c:function:: void PyThreadState_Delete(PyThreadState *tstate)

4947

4948

Destroy a thread state object. The global interpreter lock need not be held.

4949

The thread state must have been reset with a previous call to

4950

- :cfunc:`PyThreadState_Clear`.

4951

+ :c:func:`PyThreadState_Clear`.

4952

4953

4954

-.. cfunction:: PyObject* PyThreadState_GetDict()

4955

+.. c:function:: PyObject* PyThreadState_GetDict()

4956

4957

Return a dictionary in which extensions can store thread-specific state

4958

information. Each extension should use a unique key to use to store state in

4959

@@ -733,7 +743,7 @@

4960

meant that an exception was raised.

4961

4962

4963

-.. cfunction:: int PyThreadState_SetAsyncExc(long id, PyObject *exc)

4964

+.. c:function:: int PyThreadState_SetAsyncExc(long id, PyObject *exc)

4965

4966

Asynchronously raise an exception in a thread. The *id* argument is the thread

4967

id of the target thread; *exc* is the exception object to be raised. This

4968

@@ -746,18 +756,18 @@

4969

.. versionadded:: 2.3

4970

4971

4972

-.. cfunction:: void PyEval_AcquireThread(PyThreadState *tstate)

4973

+.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)

4974

4975

Acquire the global interpreter lock and set the current thread state to

4976

*tstate*, which should not be *NULL*. The lock must have been created earlier.

4977

If this thread already has the lock, deadlock ensues.

4978

4979

- :cfunc:`PyEval_RestoreThread` is a higher-level function which is always

4980

+ :c:func:`PyEval_RestoreThread` is a higher-level function which is always

4981

available (even when thread support isn't enabled or when threads have

4982

not been initialized).

4983

4984

4985

-.. cfunction:: void PyEval_ReleaseThread(PyThreadState *tstate)

4986

+.. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate)

4987

4988

Reset the current thread state to *NULL* and release the global interpreter

4989

lock. The lock must have been created earlier and must be held by the current

4990

@@ -765,29 +775,29 @@

4991

that it represents the current thread state --- if it isn't, a fatal error is

4992

reported.

4993

4994

- :cfunc:`PyEval_SaveThread` is a higher-level function which is always

4995

+ :c:func:`PyEval_SaveThread` is a higher-level function which is always

4996

available (even when thread support isn't enabled or when threads have

4997

not been initialized).

4998

4999

5000

-.. cfunction:: void PyEval_AcquireLock()

5001

+.. c:function:: void PyEval_AcquireLock()

5002

5003

Acquire the global interpreter lock. The lock must have been created earlier.

5004

If this thread already has the lock, a deadlock ensues.

5005

5006

.. warning::

5007

This function does not change the current thread state. Please use

5008

- :cfunc:`PyEval_RestoreThread` or :cfunc:`PyEval_AcquireThread`

5009

+ :c:func:`PyEval_RestoreThread` or :c:func:`PyEval_AcquireThread`

5010

instead.

5011

5012

5013

-.. cfunction:: void PyEval_ReleaseLock()

5014

+.. c:function:: void PyEval_ReleaseLock()

5015

5016

Release the global interpreter lock. The lock must have been created earlier.

5017

5018

.. warning::

5019

This function does not change the current thread state. Please use

5020

- :cfunc:`PyEval_SaveThread` or :cfunc:`PyEval_ReleaseThread`

5021

+ :c:func:`PyEval_SaveThread` or :c:func:`PyEval_ReleaseThread`

5022

instead.

5023

5024

5025

@@ -798,11 +808,11 @@

5026

are cases where you need to create several independent interpreters in the

5027

same process and perhaps even in the same thread. Sub-interpreters allow

5028

you to do that. You can switch between sub-interpreters using the

5029

-:cfunc:`PyThreadState_Swap` function. You can create and destroy them

5030

+:c:func:`PyThreadState_Swap` function. You can create and destroy them

5031

using the following functions:

5032

5033

5034

-.. cfunction:: PyThreadState* Py_NewInterpreter()

5035

+.. c:function:: PyThreadState* Py_NewInterpreter()

5036

5037

.. index::

5038

module: builtins

5039

@@ -844,13 +854,13 @@

5040

and filled with the contents of this copy; the extension's ``init`` function is

5041

not called. Note that this is different from what happens when an extension is

5042

imported after the interpreter has been completely re-initialized by calling

5043

- :cfunc:`Py_Finalize` and :cfunc:`Py_Initialize`; in that case, the extension's

5044

+ :c:func:`Py_Finalize` and :c:func:`Py_Initialize`; in that case, the extension's

5045

``initmodule`` function *is* called again.

5046

5047

.. index:: single: close() (in module os)

5048

5049

5050

-.. cfunction:: void Py_EndInterpreter(PyThreadState *tstate)

5051

+.. c:function:: void Py_EndInterpreter(PyThreadState *tstate)

5052

5053

.. index:: single: Py_Finalize()

5054

5055

@@ -859,7 +869,7 @@

5056

states below. When the call returns, the current thread state is *NULL*. All

5057

thread states associated with this interpreter are destroyed. (The global

5058

interpreter lock must be held before calling this function and is still held

5059

- when it returns.) :cfunc:`Py_Finalize` will destroy all sub-interpreters that

5060

+ when it returns.) :c:func:`Py_Finalize` will destroy all sub-interpreters that

5061

haven't been explicitly destroyed at that point.

5062

5063

5064

@@ -880,11 +890,11 @@

5065

by such objects may affect the wrong (sub-)interpreter's dictionary of loaded

5066

modules.

5067

5068

-Also note that combining this functionality with :cfunc:`PyGILState_\*` APIs

5069

+Also note that combining this functionality with :c:func:`PyGILState_\*` APIs

5070

is delicate, because these APIs assume a bijection between Python thread states

5071

and OS-level threads, an assumption broken by the presence of sub-interpreters.

5072

It is highly recommended that you don't switch sub-interpreters between a pair

5073

-of matching :cfunc:`PyGILState_Ensure` and :cfunc:`PyGILState_Release` calls.

5074

+of matching :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls.

5075

Furthermore, extensions (such as :mod:`ctypes`) using these APIs to allow calling

5076

of Python code from non-Python created threads will probably be broken when using

5077

sub-interpreters.

5078

@@ -906,7 +916,7 @@

5079

main thread where it has possession of the global interpreter lock and can

5080

perform any Python API calls.

5081

5082

-.. cfunction:: int Py_AddPendingCall(int (*func)(void *), void *arg)

5083

+.. c:function:: int Py_AddPendingCall(int (*func)(void *), void *arg)

5084

5085

.. index:: single: Py_AddPendingCall()

5086

5087

@@ -954,10 +964,10 @@

5088

in previous versions.

5089

5090

5091

-.. ctype:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

5092

+.. c:type:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

5093

5094

- The type of the trace function registered using :cfunc:`PyEval_SetProfile` and

5095

- :cfunc:`PyEval_SetTrace`. The first parameter is the object passed to the

5096

+ The type of the trace function registered using :c:func:`PyEval_SetProfile` and

5097

+ :c:func:`PyEval_SetTrace`. The first parameter is the object passed to the

5098

registration function as *obj*, *frame* is the frame object to which the event

5099

pertains, *what* is one of the constants :const:`PyTrace_CALL`,

5100

:const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`,

5101

@@ -985,18 +995,18 @@

5102

+------------------------------+--------------------------------------+

5103

5104

5105

-.. cvar:: int PyTrace_CALL

5106

+.. c:var:: int PyTrace_CALL

5107

5108

- The value of the *what* parameter to a :ctype:`Py_tracefunc` function when a new

5109

+ The value of the *what* parameter to a :c:type:`Py_tracefunc` function when a new

5110

call to a function or method is being reported, or a new entry into a generator.

5111

Note that the creation of the iterator for a generator function is not reported

5112

as there is no control transfer to the Python bytecode in the corresponding

5113

frame.

5114

5115

5116

-.. cvar:: int PyTrace_EXCEPTION

5117

+.. c:var:: int PyTrace_EXCEPTION

5118

5119

- The value of the *what* parameter to a :ctype:`Py_tracefunc` function when an

5120

+ The value of the *what* parameter to a :c:type:`Py_tracefunc` function when an

5121

exception has been raised. The callback function is called with this value for

5122

*what* when after any bytecode is processed after which the exception becomes

5123

set within the frame being executed. The effect of this is that as exception

5124

@@ -1005,37 +1015,37 @@

5125

these events; they are not needed by the profiler.

5126

5127

5128

-.. cvar:: int PyTrace_LINE

5129

+.. c:var:: int PyTrace_LINE

5130

5131

The value passed as the *what* parameter to a trace function (but not a

5132

profiling function) when a line-number event is being reported.

5133

5134

5135

-.. cvar:: int PyTrace_RETURN

5136

+.. c:var:: int PyTrace_RETURN

5137

5138

- The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a

5139

+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a

5140

call is returning without propagating an exception.

5141

5142

5143

-.. cvar:: int PyTrace_C_CALL

5144

+.. c:var:: int PyTrace_C_CALL

5145

5146

- The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a C

5147

+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C

5148

function is about to be called.

5149

5150

5151

-.. cvar:: int PyTrace_C_EXCEPTION

5152

+.. c:var:: int PyTrace_C_EXCEPTION

5153

5154

- The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a C

5155

+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C

5156

function has raised an exception.

5157

5158

5159

-.. cvar:: int PyTrace_C_RETURN

5160

+.. c:var:: int PyTrace_C_RETURN

5161

5162

- The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a C

5163

+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C

5164

function has returned.

5165

5166

5167

-.. cfunction:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

5168

+.. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

5169

5170

Set the profiler function to *func*. The *obj* parameter is passed to the

5171

function as its first parameter, and may be any Python object, or *NULL*. If

5172

@@ -1045,13 +1055,13 @@

5173

events.

5174

5175

5176

-.. cfunction:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

5177

+.. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

5178

5179

Set the tracing function to *func*. This is similar to

5180

- :cfunc:`PyEval_SetProfile`, except the tracing function does receive line-number

5181

+ :c:func:`PyEval_SetProfile`, except the tracing function does receive line-number

5182

events.

5183

5184

-.. cfunction:: PyObject* PyEval_GetCallStats(PyObject *self)

5185

+.. c:function:: PyObject* PyEval_GetCallStats(PyObject *self)

5186

5187

Return a tuple of function call counts. There are constants defined for the

5188

positions within the tuple:

5189

@@ -1103,14 +1113,14 @@

5190

These functions are only intended to be used by advanced debugging tools.

5191

5192

5193

-.. cfunction:: PyInterpreterState* PyInterpreterState_Head()

5194

+.. c:function:: PyInterpreterState* PyInterpreterState_Head()

5195

5196

Return the interpreter state object at the head of the list of all such objects.

5197

5198

.. versionadded:: 2.2

5199

5200

5201

-.. cfunction:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)

5202

+.. c:function:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)

5203

5204

Return the next interpreter state object after *interp* from the list of all

5205

such objects.

5206

@@ -1118,18 +1128,18 @@

5207

.. versionadded:: 2.2

5208

5209

5210

-.. cfunction:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)

5211

+.. c:function:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)

5212

5213

- Return the a pointer to the first :ctype:`PyThreadState` object in the list of

5214

+ Return the a pointer to the first :c:type:`PyThreadState` object in the list of

5215

threads associated with the interpreter *interp*.

5216

5217

.. versionadded:: 2.2

5218

5219

5220

-.. cfunction:: PyThreadState* PyThreadState_Next(PyThreadState *tstate)

5221

+.. c:function:: PyThreadState* PyThreadState_Next(PyThreadState *tstate)

5222

5223

Return the next thread state object after *tstate* from the list of all such

5224

- objects belonging to the same :ctype:`PyInterpreterState` object.

5225

+ objects belonging to the same :c:type:`PyInterpreterState` object.

5226

5227

.. versionadded:: 2.2

5228

5229

diff -r 8527427914a2 Doc/c-api/int.rst

5230

--- a/Doc/c-api/int.rst

5231

+++ b/Doc/c-api/int.rst

5232

@@ -8,39 +8,39 @@

5233

.. index:: object: integer

5234

5235

5236

-.. ctype:: PyIntObject

5237

+.. c:type:: PyIntObject

5238

5239

- This subtype of :ctype:`PyObject` represents a Python integer object.

5240

+ This subtype of :c:type:`PyObject` represents a Python integer object.

5241

5242

5243

-.. cvar:: PyTypeObject PyInt_Type

5244

+.. c:var:: PyTypeObject PyInt_Type

5245

5246

.. index:: single: IntType (in modules types)

5247

5248

- This instance of :ctype:`PyTypeObject` represents the Python plain integer type.

5249

+ This instance of :c:type:`PyTypeObject` represents the Python plain integer type.

5250

This is the same object as ``int`` and ``types.IntType``.

5251

5252

5253

-.. cfunction:: int PyInt_Check(PyObject *o)

5254

+.. c:function:: int PyInt_Check(PyObject *o)

5255

5256

- Return true if *o* is of type :cdata:`PyInt_Type` or a subtype of

5257

- :cdata:`PyInt_Type`.

5258

+ Return true if *o* is of type :c:data:`PyInt_Type` or a subtype of

5259

+ :c:data:`PyInt_Type`.

5260

5261

.. versionchanged:: 2.2

5262

Allowed subtypes to be accepted.

5263

5264

5265

-.. cfunction:: int PyInt_CheckExact(PyObject *o)

5266

+.. c:function:: int PyInt_CheckExact(PyObject *o)

5267

5268

- Return true if *o* is of type :cdata:`PyInt_Type`, but not a subtype of

5269

- :cdata:`PyInt_Type`.

5270

+ Return true if *o* is of type :c:data:`PyInt_Type`, but not a subtype of

5271

+ :c:data:`PyInt_Type`.

5272

5273

.. versionadded:: 2.2

5274

5275

5276

-.. cfunction:: PyObject* PyInt_FromString(char *str, char **pend, int base)

5277

+.. c:function:: PyObject* PyInt_FromString(char *str, char **pend, int base)

5278

5279

- Return a new :ctype:`PyIntObject` or :ctype:`PyLongObject` based on the string

5280

+ Return a new :c:type:`PyIntObject` or :c:type:`PyLongObject` based on the string

5281

value in *str*, which is interpreted according to the radix in *base*. If

5282

*pend* is non-*NULL*, ``*pend`` will point to the first character in *str* which

5283

follows the representation of the number. If *base* is ``0``, the radix will be

5284

@@ -49,13 +49,13 @@

5285

8 will be used; otherwise radix 10 will be used. If *base* is not ``0``, it

5286

must be between ``2`` and ``36``, inclusive. Leading spaces are ignored. If

5287

there are no digits, :exc:`ValueError` will be raised. If the string represents

5288

- a number too large to be contained within the machine's :ctype:`long int` type

5289

- and overflow warnings are being suppressed, a :ctype:`PyLongObject` will be

5290

+ a number too large to be contained within the machine's :c:type:`long int` type

5291

+ and overflow warnings are being suppressed, a :c:type:`PyLongObject` will be

5292

returned. If overflow warnings are not being suppressed, *NULL* will be

5293

returned in this case.

5294

5295

5296

-.. cfunction:: PyObject* PyInt_FromLong(long ival)

5297

+.. c:function:: PyObject* PyInt_FromLong(long ival)

5298

5299

Create a new integer object with a value of *ival*.

5300

5301

@@ -66,7 +66,7 @@

5302

undefined. :-)

5303

5304

5305

-.. cfunction:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival)

5306

+.. c:function:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival)

5307

5308

Create a new integer object with a value of *ival*. If the value is larger

5309

than ``LONG_MAX`` or smaller than ``LONG_MIN``, a long integer object is

5310

@@ -75,7 +75,7 @@

5311

.. versionadded:: 2.5

5312

5313

5314

-.. cfunction:: PyObject* PyInt_FromSize_t(size_t ival)

5315

+.. c:function:: PyObject* PyInt_FromSize_t(size_t ival)

5316

5317

Create a new integer object with a value of *ival*. If the value exceeds

5318

``LONG_MAX``, a long integer object is returned.

5319

@@ -83,47 +83,47 @@

5320

.. versionadded:: 2.5

5321

5322

5323

-.. cfunction:: long PyInt_AsLong(PyObject *io)

5324

+.. c:function:: long PyInt_AsLong(PyObject *io)

5325

5326

- Will first attempt to cast the object to a :ctype:`PyIntObject`, if it is not

5327

+ Will first attempt to cast the object to a :c:type:`PyIntObject`, if it is not

5328

already one, and then return its value. If there is an error, ``-1`` is

5329

returned, and the caller should check ``PyErr_Occurred()`` to find out whether

5330

there was an error, or whether the value just happened to be -1.

5331

5332

5333

-.. cfunction:: long PyInt_AS_LONG(PyObject *io)

5334

+.. c:function:: long PyInt_AS_LONG(PyObject *io)

5335

5336

Return the value of the object *io*. No error checking is performed.

5337

5338

5339

-.. cfunction:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)

5340

+.. c:function:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)

5341

5342

- Will first attempt to cast the object to a :ctype:`PyIntObject` or

5343

- :ctype:`PyLongObject`, if it is not already one, and then return its value as

5344

+ Will first attempt to cast the object to a :c:type:`PyIntObject` or

5345

+ :c:type:`PyLongObject`, if it is not already one, and then return its value as

5346

unsigned long. This function does not check for overflow.

5347

5348

.. versionadded:: 2.3

5349

5350

5351

-.. cfunction:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)

5352

+.. c:function:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)

5353

5354

- Will first attempt to cast the object to a :ctype:`PyIntObject` or

5355

- :ctype:`PyLongObject`, if it is not already one, and then return its value as

5356

+ Will first attempt to cast the object to a :c:type:`PyIntObject` or

5357

+ :c:type:`PyLongObject`, if it is not already one, and then return its value as

5358

unsigned long long, without checking for overflow.

5359

5360

.. versionadded:: 2.3

5361

5362

5363

-.. cfunction:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)

5364

+.. c:function:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)

5365

5366

- Will first attempt to cast the object to a :ctype:`PyIntObject` or

5367

- :ctype:`PyLongObject`, if it is not already one, and then return its value as

5368

- :ctype:`Py_ssize_t`.

5369

+ Will first attempt to cast the object to a :c:type:`PyIntObject` or

5370

+ :c:type:`PyLongObject`, if it is not already one, and then return its value as

5371

+ :c:type:`Py_ssize_t`.

5372

5373

.. versionadded:: 2.5

5374

5375

5376

-.. cfunction:: long PyInt_GetMax()

5377

+.. c:function:: long PyInt_GetMax()

5378

5379

.. index:: single: LONG_MAX

5380

5381

@@ -131,7 +131,7 @@

5382

(:const:`LONG_MAX`, as defined in the system header files).

5383

5384

5385

-.. cfunction:: int PyInt_ClearFreeList()

5386

+.. c:function:: int PyInt_ClearFreeList()

5387

5388

Clear the integer free list. Return the number of items that could not

5389

be freed.

5390

diff -r 8527427914a2 Doc/c-api/intro.rst

5391

--- a/Doc/c-api/intro.rst

5392

+++ b/Doc/c-api/intro.rst

5393

@@ -88,15 +88,15 @@

5394

.. index:: object: type

5395

5396

Most Python/C API functions have one or more arguments as well as a return value

5397

-of type :ctype:`PyObject\*`. This type is a pointer to an opaque data type

5398

+of type :c:type:`PyObject\*`. This type is a pointer to an opaque data type

5399

representing an arbitrary Python object. Since all Python object types are

5400

treated the same way by the Python language in most situations (e.g.,

5401

assignments, scope rules, and argument passing), it is only fitting that they

5402

should be represented by a single C type. Almost all Python objects live on the

5403

heap: you never declare an automatic or static variable of type

5404

-:ctype:`PyObject`, only pointer variables of type :ctype:`PyObject\*` can be

5405

+:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject\*` can be

5406

declared. The sole exception are the type objects; since these must never be

5407

-deallocated, they are typically static :ctype:`PyTypeObject` objects.

5408

+deallocated, they are typically static :c:type:`PyTypeObject` objects.

5409

5410

All Python objects (even Python integers) have a :dfn:`type` and a

5411

:dfn:`reference count`. An object's type determines what kind of object it is

5412

@@ -127,8 +127,8 @@

5413

single: Py_DECREF()

5414

5415

Reference counts are always manipulated explicitly. The normal way is to use

5416

-the macro :cfunc:`Py_INCREF` to increment an object's reference count by one,

5417

-and :cfunc:`Py_DECREF` to decrement it by one. The :cfunc:`Py_DECREF` macro

5418

+the macro :c:func:`Py_INCREF` to increment an object's reference count by one,

5419

+and :c:func:`Py_DECREF` to decrement it by one. The :c:func:`Py_DECREF` macro

5420

is considerably more complex than the incref one, since it must check whether

5421

the reference count becomes zero and then cause the object's deallocator to be

5422

called. The deallocator is a function pointer contained in the object's type

5423

@@ -159,13 +159,13 @@

5424

conceivably remove the object from the list, decrementing its reference count

5425

and possible deallocating it. The real danger is that innocent-looking

5426

operations may invoke arbitrary Python code which could do this; there is a code

5427

-path which allows control to flow back to the user from a :cfunc:`Py_DECREF`, so

5428

+path which allows control to flow back to the user from a :c:func:`Py_DECREF`, so

5429

almost any operation is potentially dangerous.

5430

5431

A safe approach is to always use the generic operations (functions whose name

5432

begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or ``PyMapping_``).

5433

These operations always increment the reference count of the object they return.

5434

-This leaves the caller with the responsibility to call :cfunc:`Py_DECREF` when

5435

+This leaves the caller with the responsibility to call :c:func:`Py_DECREF` when

5436

they are done with the result; this soon becomes second nature.

5437

5438

5439

@@ -180,7 +180,7 @@

5440

reference" means being responsible for calling Py_DECREF on it when the

5441

reference is no longer needed. Ownership can also be transferred, meaning that

5442

the code that receives ownership of the reference then becomes responsible for

5443

-eventually decref'ing it by calling :cfunc:`Py_DECREF` or :cfunc:`Py_XDECREF`

5444

+eventually decref'ing it by calling :c:func:`Py_DECREF` or :c:func:`Py_XDECREF`

5445

when it's no longer needed---or passing on this responsibility (usually to its

5446

caller). When a function passes ownership of a reference on to its caller, the

5447

caller is said to receive a *new* reference. When no ownership is transferred,

5448

@@ -198,7 +198,7 @@

5449

single: PyTuple_SetItem()

5450

5451

Few functions steal references; the two notable exceptions are

5452

-:cfunc:`PyList_SetItem` and :cfunc:`PyTuple_SetItem`, which steal a reference

5453

+:c:func:`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which steal a reference

5454

to the item (but not to the tuple or list into which the item is put!). These

5455

functions were designed to steal a reference because of a common idiom for

5456

populating a tuple or list with newly created objects; for example, the code to

5457

@@ -212,21 +212,21 @@

5458

PyTuple_SetItem(t, 1, PyInt_FromLong(2L));

5459

PyTuple_SetItem(t, 2, PyString_FromString("three"));

5460

5461

-Here, :cfunc:`PyInt_FromLong` returns a new reference which is immediately

5462

-stolen by :cfunc:`PyTuple_SetItem`. When you want to keep using an object

5463

-although the reference to it will be stolen, use :cfunc:`Py_INCREF` to grab

5464

+Here, :c:func:`PyInt_FromLong` returns a new reference which is immediately

5465

+stolen by :c:func:`PyTuple_SetItem`. When you want to keep using an object

5466

+although the reference to it will be stolen, use :c:func:`Py_INCREF` to grab

5467

another reference before calling the reference-stealing function.

5468

5469

-Incidentally, :cfunc:`PyTuple_SetItem` is the *only* way to set tuple items;

5470

-:cfunc:`PySequence_SetItem` and :cfunc:`PyObject_SetItem` refuse to do this

5471

+Incidentally, :c:func:`PyTuple_SetItem` is the *only* way to set tuple items;

5472

+:c:func:`PySequence_SetItem` and :c:func:`PyObject_SetItem` refuse to do this

5473

since tuples are an immutable data type. You should only use

5474

-:cfunc:`PyTuple_SetItem` for tuples that you are creating yourself.

5475

+:c:func:`PyTuple_SetItem` for tuples that you are creating yourself.

5476

5477

-Equivalent code for populating a list can be written using :cfunc:`PyList_New`

5478

-and :cfunc:`PyList_SetItem`.

5479

+Equivalent code for populating a list can be written using :c:func:`PyList_New`

5480

+and :c:func:`PyList_SetItem`.

5481

5482

However, in practice, you will rarely use these ways of creating and populating

5483

-a tuple or list. There's a generic function, :cfunc:`Py_BuildValue`, that can

5484

+a tuple or list. There's a generic function, :c:func:`Py_BuildValue`, that can

5485

create most common objects from C values, directed by a :dfn:`format string`.

5486

For example, the above two blocks of code could be replaced by the following

5487

(which also takes care of the error checking)::

5488

@@ -236,7 +236,7 @@

5489

tuple = Py_BuildValue("(iis)", 1, 2, "three");

5490

list = Py_BuildValue("[iis]", 1, 2, "three");

5491

5492

-It is much more common to use :cfunc:`PyObject_SetItem` and friends with items

5493

+It is much more common to use :c:func:`PyObject_SetItem` and friends with items

5494

whose references you are only borrowing, like arguments that were passed in to

5495

the function you are writing. In that case, their behaviour regarding reference

5496

counts is much saner, since you don't have to increment a reference count so you

5497

@@ -270,15 +270,15 @@

5498

you ownership of the reference. The reason is simple: in many cases, the

5499

returned object is created on the fly, and the reference you get is the only

5500

reference to the object. Therefore, the generic functions that return object

5501

-references, like :cfunc:`PyObject_GetItem` and :cfunc:`PySequence_GetItem`,

5502

+references, like :c:func:`PyObject_GetItem` and :c:func:`PySequence_GetItem`,

5503

always return a new reference (the caller becomes the owner of the reference).

5504

5505

It is important to realize that whether you own a reference returned by a

5506

function depends on which function you call only --- *the plumage* (the type of

5507

the object passed as an argument to the function) *doesn't enter into it!*

5508

-Thus, if you extract an item from a list using :cfunc:`PyList_GetItem`, you

5509

+Thus, if you extract an item from a list using :c:func:`PyList_GetItem`, you

5510

don't own the reference --- but if you obtain the same item from the same list

5511

-using :cfunc:`PySequence_GetItem` (which happens to take exactly the same

5512

+using :c:func:`PySequence_GetItem` (which happens to take exactly the same

5513

arguments), you do own a reference to the returned object.

5514

5515

.. index::

5516

@@ -286,8 +286,8 @@

5517

single: PySequence_GetItem()

5518

5519

Here is an example of how you could write a function that computes the sum of

5520

-the items in a list of integers; once using :cfunc:`PyList_GetItem`, and once

5521

-using :cfunc:`PySequence_GetItem`. ::

5522

+the items in a list of integers; once using :c:func:`PyList_GetItem`, and once

5523

+using :c:func:`PySequence_GetItem`. ::

5524

5525

long

5526

sum_list(PyObject *list)

5527

@@ -340,8 +340,8 @@

5528

-----

5529

5530

There are few other data types that play a significant role in the Python/C

5531

-API; most are simple C types such as :ctype:`int`, :ctype:`long`,

5532

-:ctype:`double` and :ctype:`char\*`. A few structure types are used to

5533

+API; most are simple C types such as :c:type:`int`, :c:type:`long`,

5534

+:c:type:`double` and :c:type:`char\*`. A few structure types are used to

5535

describe static tables used to list the functions exported by a module or the

5536

data attributes of a new object type, and another is used to describe the value

5537

of a complex number. These will be discussed together with the functions that

5538

@@ -370,7 +370,7 @@

5539

A few functions return a Boolean true/false result, with false indicating an

5540

error. Very few functions return no explicit error indicator or have an

5541

ambiguous return value, and require explicit testing for errors with

5542

-:cfunc:`PyErr_Occurred`. These exceptions are always explicitly documented.

5543

+:c:func:`PyErr_Occurred`. These exceptions are always explicitly documented.

5544

5545

.. index::

5546

single: PyErr_SetString()

5547

@@ -379,11 +379,11 @@

5548

Exception state is maintained in per-thread storage (this is equivalent to

5549

using global storage in an unthreaded application). A thread can be in one of

5550

two states: an exception has occurred, or not. The function

5551

-:cfunc:`PyErr_Occurred` can be used to check for this: it returns a borrowed

5552

+:c:func:`PyErr_Occurred` can be used to check for this: it returns a borrowed

5553

reference to the exception type object when an exception has occurred, and

5554

*NULL* otherwise. There are a number of functions to set the exception state:

5555

-:cfunc:`PyErr_SetString` is the most common (though not the most general)

5556

-function to set the exception state, and :cfunc:`PyErr_Clear` clears the

5557

+:c:func:`PyErr_SetString` is the most common (though not the most general)

5558

+function to set the exception state, and :c:func:`PyErr_Clear` clears the

5559

exception state.

5560

5561

.. index::

5562

@@ -424,7 +424,7 @@

5563

.. index:: single: sum_sequence()

5564

5565

A simple example of detecting exceptions and passing them on is shown in the

5566

-:cfunc:`sum_sequence` example above. It so happens that that example doesn't

5567

+:c:func:`sum_sequence` example above. It so happens that that example doesn't

5568

need to clean up any owned references when it detects an error. The following

5569

example function shows some error cleanup. First, to remind you why you like

5570

Python, we show the equivalent Python code::

5571

@@ -491,10 +491,10 @@

5572

single: Py_XDECREF()

5573

5574

This example represents an endorsed use of the ``goto`` statement in C!

5575

-It illustrates the use of :cfunc:`PyErr_ExceptionMatches` and

5576

-:cfunc:`PyErr_Clear` to handle specific exceptions, and the use of

5577

-:cfunc:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the

5578

-``'X'`` in the name; :cfunc:`Py_DECREF` would crash when confronted with a

5579

+It illustrates the use of :c:func:`PyErr_ExceptionMatches` and

5580

+:c:func:`PyErr_Clear` to handle specific exceptions, and the use of

5581

+:c:func:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the

5582

+``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a

5583

*NULL* reference). It is important that the variables used to hold owned

5584

references are initialized to *NULL* for this to work; likewise, the proposed

5585

return value is initialized to ``-1`` (failure) and only set to success after

5586

@@ -520,20 +520,20 @@

5587

triple: module; search; path

5588

single: path (in module sys)

5589

5590

-The basic initialization function is :cfunc:`Py_Initialize`. This initializes

5591

+The basic initialization function is :c:func:`Py_Initialize`. This initializes

5592

the table of loaded modules, and creates the fundamental modules

5593

:mod:`__builtin__`, :mod:`__main__`, :mod:`sys`, and :mod:`exceptions`. It also

5594

initializes the module search path (``sys.path``).

5595

5596

.. index:: single: PySys_SetArgvEx()

5597

5598

-:cfunc:`Py_Initialize` does not set the "script argument list" (``sys.argv``).

5599

+:c:func:`Py_Initialize` does not set the "script argument list" (``sys.argv``).

5600

If this variable is needed by Python code that will be executed later, it must

5601

be set explicitly with a call to ``PySys_SetArgvEx(argc, argv, updatepath)``

5602

-after the call to :cfunc:`Py_Initialize`.

5603

+after the call to :c:func:`Py_Initialize`.

5604

5605

On most systems (in particular, on Unix and Windows, although the details are

5606

-slightly different), :cfunc:`Py_Initialize` calculates the module search path

5607

+slightly different), :c:func:`Py_Initialize` calculates the module search path

5608

based upon its best guess for the location of the standard Python interpreter

5609

executable, assuming that the Python library is found in a fixed location

5610

relative to the Python interpreter executable. In particular, it looks for a

5611

@@ -557,22 +557,22 @@

5612

single: Py_GetProgramFullPath()

5613

5614

The embedding application can steer the search by calling

5615

-``Py_SetProgramName(file)`` *before* calling :cfunc:`Py_Initialize`. Note that

5616

+``Py_SetProgramName(file)`` *before* calling :c:func:`Py_Initialize`. Note that

5617

:envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` is still

5618

inserted in front of the standard path. An application that requires total

5619

-control has to provide its own implementation of :cfunc:`Py_GetPath`,

5620

-:cfunc:`Py_GetPrefix`, :cfunc:`Py_GetExecPrefix`, and

5621

-:cfunc:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`).

5622

+control has to provide its own implementation of :c:func:`Py_GetPath`,

5623

+:c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and

5624

+:c:func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`).

5625

5626

.. index:: single: Py_IsInitialized()

5627

5628

Sometimes, it is desirable to "uninitialize" Python. For instance, the

5629

application may want to start over (make another call to

5630

-:cfunc:`Py_Initialize`) or the application is simply done with its use of

5631

+:c:func:`Py_Initialize`) or the application is simply done with its use of

5632

Python and wants to free memory allocated by Python. This can be accomplished

5633

-by calling :cfunc:`Py_Finalize`. The function :cfunc:`Py_IsInitialized` returns

5634

+by calling :c:func:`Py_Finalize`. The function :c:func:`Py_IsInitialized` returns

5635

true if Python is currently in the initialized state. More information about

5636

-these functions is given in a later chapter. Notice that :cfunc:`Py_Finalize`

5637

+these functions is given in a later chapter. Notice that :c:func:`Py_Finalize`

5638

does *not* free all memory allocated by the Python interpreter, e.g. memory

5639

allocated by extension modules currently cannot be released.

5640

5641

@@ -592,11 +592,11 @@

5642

allocator, or low-level profiling of the main interpreter loop. Only the most

5643

frequently-used builds will be described in the remainder of this section.

5644

5645

-Compiling the interpreter with the :cmacro:`Py_DEBUG` macro defined produces

5646

-what is generally meant by "a debug build" of Python. :cmacro:`Py_DEBUG` is

5647

-enabled in the Unix build by adding :option:`--with-pydebug` to the

5648

-:file:`configure` command. It is also implied by the presence of the

5649

-not-Python-specific :cmacro:`_DEBUG` macro. When :cmacro:`Py_DEBUG` is enabled

5650

+Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined produces

5651

+what is generally meant by "a debug build" of Python. :c:macro:`Py_DEBUG` is

5652

+enabled in the Unix build by adding ``--with-pydebug`` to the

5653

+:file:`./configure` command. It is also implied by the presence of the

5654

+not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`Py_DEBUG` is enabled

5655

in the Unix build, compiler optimization is disabled.

5656

5657

In addition to the reference count debugging described below, the following

5658

@@ -625,11 +625,11 @@

5659

5660

There may be additional checks not mentioned here.

5661

5662

-Defining :cmacro:`Py_TRACE_REFS` enables reference tracing. When defined, a

5663

+Defining :c:macro:`Py_TRACE_REFS` enables reference tracing. When defined, a

5664

circular doubly linked list of active objects is maintained by adding two extra

5665

-fields to every :ctype:`PyObject`. Total allocations are tracked as well. Upon

5666

+fields to every :c:type:`PyObject`. Total allocations are tracked as well. Upon

5667

exit, all existing references are printed. (In interactive mode this happens

5668

-after every statement run by the interpreter.) Implied by :cmacro:`Py_DEBUG`.

5669

+after every statement run by the interpreter.) Implied by :c:macro:`Py_DEBUG`.

5670

5671

Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution

5672

for more detailed information.

5673

diff -r 8527427914a2 Doc/c-api/iter.rst

5674

--- a/Doc/c-api/iter.rst

5675

+++ b/Doc/c-api/iter.rst

5676

@@ -10,12 +10,12 @@

5677

There are only a couple of functions specifically for working with iterators.

5678

5679

5680

-.. cfunction:: int PyIter_Check(PyObject *o)

5681

+.. c:function:: int PyIter_Check(PyObject *o)

5682

5683

Return true if the object *o* supports the iterator protocol.

5684

5685

5686

-.. cfunction:: PyObject* PyIter_Next(PyObject *o)

5687

+.. c:function:: PyObject* PyIter_Next(PyObject *o)

5688

5689

Return the next value from the iteration *o*. If the object is an iterator,

5690

this retrieves the next value from the iteration, and returns *NULL* with no

5691

diff -r 8527427914a2 Doc/c-api/iterator.rst

5692

--- a/Doc/c-api/iterator.rst

5693

+++ b/Doc/c-api/iterator.rst

5694

@@ -12,23 +12,23 @@

5695

sentinel value is returned.

5696

5697

5698

-.. cvar:: PyTypeObject PySeqIter_Type

5699

+.. c:var:: PyTypeObject PySeqIter_Type

5700

5701

- Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the

5702

+ Type object for iterator objects returned by :c:func:`PySeqIter_New` and the

5703

one-argument form of the :func:`iter` built-in function for built-in sequence

5704

types.

5705

5706

.. versionadded:: 2.2

5707

5708

5709

-.. cfunction:: int PySeqIter_Check(op)

5710

+.. c:function:: int PySeqIter_Check(op)

5711

5712

- Return true if the type of *op* is :cdata:`PySeqIter_Type`.

5713

+ Return true if the type of *op* is :c:data:`PySeqIter_Type`.

5714

5715

.. versionadded:: 2.2

5716

5717

5718

-.. cfunction:: PyObject* PySeqIter_New(PyObject *seq)

5719

+.. c:function:: PyObject* PySeqIter_New(PyObject *seq)

5720

5721

Return an iterator that works with a general sequence object, *seq*. The

5722

iteration ends when the sequence raises :exc:`IndexError` for the subscripting

5723

@@ -37,22 +37,22 @@

5724

.. versionadded:: 2.2

5725

5726

5727

-.. cvar:: PyTypeObject PyCallIter_Type

5728

+.. c:var:: PyTypeObject PyCallIter_Type

5729

5730

- Type object for iterator objects returned by :cfunc:`PyCallIter_New` and the

5731

+ Type object for iterator objects returned by :c:func:`PyCallIter_New` and the

5732

two-argument form of the :func:`iter` built-in function.

5733

5734

.. versionadded:: 2.2

5735

5736

5737

-.. cfunction:: int PyCallIter_Check(op)

5738

+.. c:function:: int PyCallIter_Check(op)

5739

5740

- Return true if the type of *op* is :cdata:`PyCallIter_Type`.

5741

+ Return true if the type of *op* is :c:data:`PyCallIter_Type`.

5742

5743

.. versionadded:: 2.2

5744

5745

5746

-.. cfunction:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)

5747

+.. c:function:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)

5748

5749

Return a new iterator. The first parameter, *callable*, can be any Python

5750

callable object that can be called with no parameters; each call to it should

5751

diff -r 8527427914a2 Doc/c-api/list.rst

5752

--- a/Doc/c-api/list.rst

5753

+++ b/Doc/c-api/list.rst

5754

@@ -8,18 +8,18 @@

5755

.. index:: object: list

5756

5757

5758

-.. ctype:: PyListObject

5759

+.. c:type:: PyListObject

5760

5761

- This subtype of :ctype:`PyObject` represents a Python list object.

5762

+ This subtype of :c:type:`PyObject` represents a Python list object.

5763

5764

5765

-.. cvar:: PyTypeObject PyList_Type

5766

+.. c:var:: PyTypeObject PyList_Type

5767

5768

- This instance of :ctype:`PyTypeObject` represents the Python list type. This

5769

+ This instance of :c:type:`PyTypeObject` represents the Python list type. This

5770

is the same object as ``list`` in the Python layer.

5771

5772

5773

-.. cfunction:: int PyList_Check(PyObject *p)

5774

+.. c:function:: int PyList_Check(PyObject *p)

5775

5776

Return true if *p* is a list object or an instance of a subtype of the list

5777

type.

5778

@@ -28,7 +28,7 @@

5779

Allowed subtypes to be accepted.

5780

5781

5782

-.. cfunction:: int PyList_CheckExact(PyObject *p)

5783

+.. c:function:: int PyList_CheckExact(PyObject *p)

5784

5785

Return true if *p* is a list object, but not an instance of a subtype of

5786

the list type.

5787

@@ -36,7 +36,7 @@

5788

.. versionadded:: 2.2

5789

5790

5791

-.. cfunction:: PyObject* PyList_New(Py_ssize_t len)

5792

+.. c:function:: PyObject* PyList_New(Py_ssize_t len)

5793

5794

Return a new list of length *len* on success, or *NULL* on failure.

5795

5796

@@ -44,15 +44,15 @@

5797

5798

If *len* is greater than zero, the returned list object's items are

5799

set to ``NULL``. Thus you cannot use abstract API functions such as

5800

- :cfunc:`PySequence_SetItem` or expose the object to Python code before

5801

- setting all items to a real object with :cfunc:`PyList_SetItem`.

5802

+ :c:func:`PySequence_SetItem` or expose the object to Python code before

5803

+ setting all items to a real object with :c:func:`PyList_SetItem`.

5804

5805

.. versionchanged:: 2.5

5806

- This function used an :ctype:`int` for *size*. This might require

5807

+ This function used an :c:type:`int` for *size*. This might require

5808

changes in your code for properly supporting 64-bit systems.

5809

5810

5811

-.. cfunction:: Py_ssize_t PyList_Size(PyObject *list)

5812

+.. c:function:: Py_ssize_t PyList_Size(PyObject *list)

5813

5814

.. index:: builtin: len

5815

5816

@@ -60,20 +60,20 @@

5817

``len(list)`` on a list object.

5818

5819

.. versionchanged:: 2.5

5820

- This function returned an :ctype:`int`. This might require changes in

5821

+ This function returned an :c:type:`int`. This might require changes in

5822

your code for properly supporting 64-bit systems.

5823

5824

5825

-.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)

5826

+.. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list)

5827

5828

- Macro form of :cfunc:`PyList_Size` without error checking.

5829

+ Macro form of :c:func:`PyList_Size` without error checking.

5830

5831

.. versionchanged:: 2.5

5832

- This macro returned an :ctype:`int`. This might require changes in your

5833

+ This macro returned an :c:type:`int`. This might require changes in your

5834

code for properly supporting 64-bit systems.

5835

5836

5837

-.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)

5838

+.. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)

5839

5840

Return the object at position *index* in the list pointed to by *list*. The

5841

position must be positive, indexing from the end of the list is not

5842

@@ -81,20 +81,20 @@

5843

:exc:`IndexError` exception.

5844

5845

.. versionchanged:: 2.5

5846

- This function used an :ctype:`int` for *index*. This might require

5847

+ This function used an :c:type:`int` for *index*. This might require

5848

changes in your code for properly supporting 64-bit systems.

5849

5850

5851

-.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)

5852

+.. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)

5853

5854

- Macro form of :cfunc:`PyList_GetItem` without error checking.

5855

+ Macro form of :c:func:`PyList_GetItem` without error checking.

5856

5857

.. versionchanged:: 2.5

5858

- This macro used an :ctype:`int` for *i*. This might require changes in

5859

+ This macro used an :c:type:`int` for *i*. This might require changes in

5860

your code for properly supporting 64-bit systems.

5861

5862

5863

-.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)

5864

+.. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)

5865

5866

Set the item at index *index* in list to *item*. Return ``0`` on success

5867

or ``-1`` on failure.

5868

@@ -105,46 +105,46 @@

5869

an item already in the list at the affected position.

5870

5871

.. versionchanged:: 2.5

5872

- This function used an :ctype:`int` for *index*. This might require

5873

+ This function used an :c:type:`int` for *index*. This might require

5874

changes in your code for properly supporting 64-bit systems.

5875

5876

5877

-.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)

5878

+.. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)

5879

5880

- Macro form of :cfunc:`PyList_SetItem` without error checking. This is

5881

+ Macro form of :c:func:`PyList_SetItem` without error checking. This is

5882

normally only used to fill in new lists where there is no previous content.

5883

5884

.. note::

5885

5886

This macro "steals" a reference to *item*, and, unlike

5887

- :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that

5888

+ :c:func:`PyList_SetItem`, does *not* discard a reference to any item that

5889

it being replaced; any reference in *list* at position *i* will be

5890

leaked.

5891

5892

.. versionchanged:: 2.5

5893

- This macro used an :ctype:`int` for *i*. This might require

5894

+ This macro used an :c:type:`int` for *i*. This might require

5895

changes in your code for properly supporting 64-bit systems.

5896

5897

5898

-.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)

5899

+.. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)

5900

5901

Insert the item *item* into list *list* in front of index *index*. Return

5902

``0`` if successful; return ``-1`` and set an exception if unsuccessful.

5903

Analogous to ``list.insert(index, item)``.

5904

5905

.. versionchanged:: 2.5

5906

- This function used an :ctype:`int` for *index*. This might require

5907

+ This function used an :c:type:`int` for *index*. This might require

5908

changes in your code for properly supporting 64-bit systems.

5909

5910

5911

-.. cfunction:: int PyList_Append(PyObject *list, PyObject *item)

5912

+.. c:function:: int PyList_Append(PyObject *list, PyObject *item)

5913

5914

Append the object *item* at the end of list *list*. Return ``0`` if

5915

successful; return ``-1`` and set an exception if unsuccessful. Analogous

5916

to ``list.append(item)``.

5917

5918

5919

-.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)

5920

+.. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)

5921

5922

Return a list of the objects in *list* containing the objects *between* *low*

5923

and *high*. Return *NULL* and set an exception if unsuccessful. Analogous

5924

@@ -152,11 +152,11 @@

5925

supported.

5926

5927

.. versionchanged:: 2.5

5928

- This function used an :ctype:`int` for *low* and *high*. This might

5929

+ This function used an :c:type:`int` for *low* and *high*. This might

5930

require changes in your code for properly supporting 64-bit systems.

5931

5932

5933

-.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)

5934

+.. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)

5935

5936

Set the slice of *list* between *low* and *high* to the contents of

5937

*itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may

5938

@@ -165,23 +165,23 @@

5939

slicing from Python, are not supported.

5940

5941

.. versionchanged:: 2.5

5942

- This function used an :ctype:`int` for *low* and *high*. This might

5943

+ This function used an :c:type:`int` for *low* and *high*. This might

5944

require changes in your code for properly supporting 64-bit systems.

5945

5946

5947

-.. cfunction:: int PyList_Sort(PyObject *list)

5948

+.. c:function:: int PyList_Sort(PyObject *list)

5949

5950

Sort the items of *list* in place. Return ``0`` on success, ``-1`` on

5951

failure. This is equivalent to ``list.sort()``.

5952

5953

5954

-.. cfunction:: int PyList_Reverse(PyObject *list)

5955

+.. c:function:: int PyList_Reverse(PyObject *list)

5956

5957

Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on

5958

failure. This is the equivalent of ``list.reverse()``.

5959

5960

5961

-.. cfunction:: PyObject* PyList_AsTuple(PyObject *list)

5962

+.. c:function:: PyObject* PyList_AsTuple(PyObject *list)

5963

5964

.. index:: builtin: tuple

5965

5966

diff -r 8527427914a2 Doc/c-api/long.rst

5967

--- a/Doc/c-api/long.rst

5968

+++ b/Doc/c-api/long.rst

5969

@@ -8,100 +8,100 @@

5970

.. index:: object: long integer

5971

5972

5973

-.. ctype:: PyLongObject

5974

+.. c:type:: PyLongObject

5975

5976

- This subtype of :ctype:`PyObject` represents a Python long integer object.

5977

+ This subtype of :c:type:`PyObject` represents a Python long integer object.

5978

5979

5980

-.. cvar:: PyTypeObject PyLong_Type

5981

+.. c:var:: PyTypeObject PyLong_Type

5982

5983

.. index:: single: LongType (in modules types)

5984

5985

- This instance of :ctype:`PyTypeObject` represents the Python long integer type.

5986

+ This instance of :c:type:`PyTypeObject` represents the Python long integer type.

5987

This is the same object as ``long`` and ``types.LongType``.

5988

5989

5990

-.. cfunction:: int PyLong_Check(PyObject *p)

5991

+.. c:function:: int PyLong_Check(PyObject *p)

5992

5993

- Return true if its argument is a :ctype:`PyLongObject` or a subtype of

5994

- :ctype:`PyLongObject`.

5995

+ Return true if its argument is a :c:type:`PyLongObject` or a subtype of

5996

+ :c:type:`PyLongObject`.

5997

5998

.. versionchanged:: 2.2

5999

Allowed subtypes to be accepted.

6000

6001

6002

-.. cfunction:: int PyLong_CheckExact(PyObject *p)

6003

+.. c:function:: int PyLong_CheckExact(PyObject *p)

6004

6005

- Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of

6006

- :ctype:`PyLongObject`.

6007

+ Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of

6008

+ :c:type:`PyLongObject`.

6009

6010

.. versionadded:: 2.2

6011

6012

6013

-.. cfunction:: PyObject* PyLong_FromLong(long v)

6014

+.. c:function:: PyObject* PyLong_FromLong(long v)

6015

6016

- Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.

6017

+ Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure.

6018

6019

6020

-.. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v)

6021

+.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)

6022

6023

- Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or

6024

+ Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or

6025

*NULL* on failure.

6026

6027

6028

-.. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)

6029

+.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)

6030

6031

- Return a new :ctype:`PyLongObject` object from a C :ctype:`Py_ssize_t`, or

6032

+ Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or

6033

*NULL* on failure.

6034

6035

.. versionadded:: 2.6

6036

6037

6038

-.. cfunction:: PyObject* PyLong_FromSize_t(size_t v)

6039

+.. c:function:: PyObject* PyLong_FromSize_t(size_t v)

6040

6041

- Return a new :ctype:`PyLongObject` object from a C :ctype:`size_t`, or

6042

+ Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or

6043

*NULL* on failure.

6044

6045

.. versionadded:: 2.6

6046

6047

6048

-.. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)

6049

+.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)

6050

6051

- Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*

6052

+ Return a new :c:type:`PyLongObject` object with a value of *v*, or *NULL*

6053

on failure.

6054

6055

.. versionadded:: 2.6

6056

6057

6058

-.. cfunction:: PyObject* PyLong_FromSize_t(size_t v)

6059

+.. c:function:: PyObject* PyLong_FromSize_t(size_t v)

6060

6061

- Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*

6062

+ Return a new :c:type:`PyLongObject` object with a value of *v*, or *NULL*

6063

on failure.

6064

6065

.. versionadded:: 2.6

6066

6067

6068

-.. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)

6069

+.. c:function:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)

6070

6071

- Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL*

6072

+ Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or *NULL*

6073

on failure.

6074

6075

6076

-.. cfunction:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)

6077

+.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)

6078

6079

- Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long long`,

6080

+ Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`,

6081

or *NULL* on failure.

6082

6083

6084

-.. cfunction:: PyObject* PyLong_FromDouble(double v)

6085

+.. c:function:: PyObject* PyLong_FromDouble(double v)

6086

6087

- Return a new :ctype:`PyLongObject` object from the integer part of *v*, or

6088

+ Return a new :c:type:`PyLongObject` object from the integer part of *v*, or

6089

*NULL* on failure.

6090

6091

6092

-.. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base)

6093

+.. c:function:: PyObject* PyLong_FromString(char *str, char **pend, int base)

6094

6095

- Return a new :ctype:`PyLongObject` based on the string value in *str*, which is

6096

+ Return a new :c:type:`PyLongObject` based on the string value in *str*, which is

6097

interpreted according to the radix in *base*. If *pend* is non-*NULL*,

6098

*\*pend* will point to the first character in *str* which follows the

6099

representation of the number. If *base* is ``0``, the radix will be determined

6100

@@ -112,7 +112,7 @@

6101

no digits, :exc:`ValueError` will be raised.

6102

6103

6104

-.. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)

6105

+.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)

6106

6107

Convert a sequence of Unicode digits to a Python long integer value. The first

6108

parameter, *u*, points to the first character of the Unicode string, *length*

6109

@@ -123,14 +123,14 @@

6110

.. versionadded:: 1.6

6111

6112

.. versionchanged:: 2.5

6113

- This function used an :ctype:`int` for *length*. This might require

6114

+ This function used an :c:type:`int` for *length*. This might require

6115

changes in your code for properly supporting 64-bit systems.

6116

6117

6118

-.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)

6119

+.. c:function:: PyObject* PyLong_FromVoidPtr(void *p)

6120

6121

Create a Python integer or long integer from the pointer *p*. The pointer value

6122

- can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.

6123

+ can be retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`.

6124

6125

.. versionadded:: 1.5.2

6126

6127

@@ -138,20 +138,20 @@

6128

If the integer is larger than LONG_MAX, a positive long integer is returned.

6129

6130

6131

-.. cfunction:: long PyLong_AsLong(PyObject *pylong)

6132

+.. c:function:: long PyLong_AsLong(PyObject *pylong)

6133

6134

.. index::

6135

single: LONG_MAX

6136

single: OverflowError (built-in exception)

6137

6138

- Return a C :ctype:`long` representation of the contents of *pylong*. If

6139

+ Return a C :c:type:`long` representation of the contents of *pylong*. If

6140

*pylong* is greater than :const:`LONG_MAX`, an :exc:`OverflowError` is raised

6141

and ``-1`` will be returned.

6142

6143

6144

-.. cfunction:: long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow)

6145

+.. c:function:: long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow)

6146

6147

- Return a C :ctype:`long` representation of the contents of

6148

+ Return a C :c:type:`long` representation of the contents of

6149

*pylong*. If *pylong* is greater than :const:`LONG_MAX` or less

6150

than :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``,

6151

respectively, and return ``-1``; otherwise, set *\*overflow* to

6152

@@ -162,9 +162,9 @@

6153

.. versionadded:: 2.7

6154

6155

6156

-.. cfunction:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow)

6157

+.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow)

6158

6159

- Return a C :ctype:`long long` representation of the contents of

6160

+ Return a C :c:type:`long long` representation of the contents of

6161

*pylong*. If *pylong* is greater than :const:`PY_LLONG_MAX` or less

6162

than :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``,

6163

respectively, and return ``-1``; otherwise, set *\*overflow* to

6164

@@ -175,61 +175,61 @@

6165

.. versionadded:: 2.7

6166

6167

6168

-.. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

6169

+.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

6170

6171

.. index::

6172

single: PY_SSIZE_T_MAX

6173

single: OverflowError (built-in exception)

6174

6175

- Return a C :ctype:`Py_ssize_t` representation of the contents of *pylong*. If

6176

+ Return a C :c:type:`Py_ssize_t` representation of the contents of *pylong*. If

6177

*pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is raised

6178

and ``-1`` will be returned.

6179

6180

.. versionadded:: 2.6

6181

6182

6183

-.. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

6184

+.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

6185

6186

.. index::

6187

single: ULONG_MAX

6188

single: OverflowError (built-in exception)

6189

6190

- Return a C :ctype:`unsigned long` representation of the contents of *pylong*.

6191

+ Return a C :c:type:`unsigned long` representation of the contents of *pylong*.

6192

If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is

6193

raised.

6194

6195

6196

-.. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

6197

+.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

6198

6199

.. index::

6200

single: PY_SSIZE_T_MAX

6201

6202

- Return a :ctype:`Py_ssize_t` representation of the contents of *pylong*. If

6203

+ Return a :c:type:`Py_ssize_t` representation of the contents of *pylong*. If

6204

*pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is

6205

raised.

6206

6207

.. versionadded:: 2.6

6208

6209

6210

-.. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)

6211

+.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)

6212

6213

.. index::

6214

single: OverflowError (built-in exception)

6215

6216

- Return a C :ctype:`long long` from a Python long integer. If

6217

- *pylong* cannot be represented as a :ctype:`long long`, an

6218

+ Return a C :c:type:`long long` from a Python long integer. If

6219

+ *pylong* cannot be represented as a :c:type:`long long`, an

6220

:exc:`OverflowError` is raised and ``-1`` is returned.

6221

6222

.. versionadded:: 2.2

6223

6224

6225

-.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)

6226

+.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)

6227

6228

.. index::

6229

single: OverflowError (built-in exception)

6230

6231

- Return a C :ctype:`unsigned long long` from a Python long integer. If

6232

- *pylong* cannot be represented as an :ctype:`unsigned long long`, an

6233

+ Return a C :c:type:`unsigned long long` from a Python long integer. If

6234

+ *pylong* cannot be represented as an :c:type:`unsigned long long`, an

6235

:exc:`OverflowError` is raised and ``(unsigned long long)-1`` is

6236

returned.

6237

6238

@@ -240,35 +240,35 @@

6239

:exc:`TypeError`.

6240

6241

6242

-.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)

6243

+.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)

6244

6245

- Return a C :ctype:`unsigned long` from a Python long integer, without checking

6246

+ Return a C :c:type:`unsigned long` from a Python long integer, without checking

6247

for overflow.

6248

6249

.. versionadded:: 2.3

6250

6251

6252

-.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)

6253

+.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)

6254

6255

- Return a C :ctype:`unsigned long long` from a Python long integer, without

6256

+ Return a C :c:type:`unsigned long long` from a Python long integer, without

6257

checking for overflow.

6258

6259

.. versionadded:: 2.3

6260

6261

6262

-.. cfunction:: double PyLong_AsDouble(PyObject *pylong)

6263

+.. c:function:: double PyLong_AsDouble(PyObject *pylong)

6264

6265

- Return a C :ctype:`double` representation of the contents of *pylong*. If

6266

- *pylong* cannot be approximately represented as a :ctype:`double`, an

6267

+ Return a C :c:type:`double` representation of the contents of *pylong*. If

6268

+ *pylong* cannot be approximately represented as a :c:type:`double`, an

6269

:exc:`OverflowError` exception is raised and ``-1.0`` will be returned.

6270

6271

6272

-.. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong)

6273

+.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)

6274

6275

- Convert a Python integer or long integer *pylong* to a C :ctype:`void` pointer.

6276

+ Convert a Python integer or long integer *pylong* to a C :c:type:`void` pointer.

6277

If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This

6278

- is only assured to produce a usable :ctype:`void` pointer for values created

6279

- with :cfunc:`PyLong_FromVoidPtr`.

6280

+ is only assured to produce a usable :c:type:`void` pointer for values created

6281

+ with :c:func:`PyLong_FromVoidPtr`.

6282

6283

.. versionadded:: 1.5.2

6284

6285

diff -r 8527427914a2 Doc/c-api/mapping.rst

6286

--- a/Doc/c-api/mapping.rst

6287

+++ b/Doc/c-api/mapping.rst

6288

@@ -6,13 +6,13 @@

6289

================

6290

6291

6292

-.. cfunction:: int PyMapping_Check(PyObject *o)

6293

+.. c:function:: int PyMapping_Check(PyObject *o)

6294

6295

Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This

6296

function always succeeds.

6297

6298

6299

-.. cfunction:: Py_ssize_t PyMapping_Size(PyObject *o)

6300

+.. c:function:: Py_ssize_t PyMapping_Size(PyObject *o)

6301

Py_ssize_t PyMapping_Length(PyObject *o)

6302

6303

.. index:: builtin: len

6304

@@ -22,62 +22,62 @@

6305

expression ``len(o)``.

6306

6307

.. versionchanged:: 2.5

6308

- These functions returned an :ctype:`int` type. This might require

6309

+ These functions returned an :c:type:`int` type. This might require

6310

changes in your code for properly supporting 64-bit systems.

6311

6312

6313

-.. cfunction:: int PyMapping_DelItemString(PyObject *o, char *key)

6314

+.. c:function:: int PyMapping_DelItemString(PyObject *o, char *key)

6315

6316

Remove the mapping for object *key* from the object *o*. Return ``-1`` on

6317

failure. This is equivalent to the Python statement ``del o[key]``.

6318

6319

6320

-.. cfunction:: int PyMapping_DelItem(PyObject *o, PyObject *key)

6321

+.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)

6322

6323

Remove the mapping for object *key* from the object *o*. Return ``-1`` on

6324

failure. This is equivalent to the Python statement ``del o[key]``.

6325

6326

6327

-.. cfunction:: int PyMapping_HasKeyString(PyObject *o, char *key)

6328

+.. c:function:: int PyMapping_HasKeyString(PyObject *o, char *key)

6329

6330

On success, return ``1`` if the mapping object has the key *key* and ``0``

6331

otherwise. This is equivalent to ``o[key]``, returning ``True`` on success

6332

and ``False`` on an exception. This function always succeeds.

6333

6334

6335

-.. cfunction:: int PyMapping_HasKey(PyObject *o, PyObject *key)

6336

+.. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key)

6337

6338

Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.

6339

This is equivalent to ``o[key]``, returning ``True`` on success and ``False``

6340

on an exception. This function always succeeds.

6341

6342

6343

-.. cfunction:: PyObject* PyMapping_Keys(PyObject *o)

6344

+.. c:function:: PyObject* PyMapping_Keys(PyObject *o)

6345

6346

On success, return a list of the keys in object *o*. On failure, return *NULL*.

6347

This is equivalent to the Python expression ``o.keys()``.

6348

6349

6350

-.. cfunction:: PyObject* PyMapping_Values(PyObject *o)

6351

+.. c:function:: PyObject* PyMapping_Values(PyObject *o)

6352

6353

On success, return a list of the values in object *o*. On failure, return

6354

*NULL*. This is equivalent to the Python expression ``o.values()``.

6355

6356

6357

-.. cfunction:: PyObject* PyMapping_Items(PyObject *o)

6358

+.. c:function:: PyObject* PyMapping_Items(PyObject *o)

6359

6360

On success, return a list of the items in object *o*, where each item is a tuple

6361

containing a key-value pair. On failure, return *NULL*. This is equivalent to

6362

the Python expression ``o.items()``.

6363

6364

6365

-.. cfunction:: PyObject* PyMapping_GetItemString(PyObject *o, char *key)

6366

+.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, char *key)

6367

6368

Return element of *o* corresponding to the object *key* or *NULL* on failure.

6369

This is the equivalent of the Python expression ``o[key]``.

6370

6371

6372

-.. cfunction:: int PyMapping_SetItemString(PyObject *o, char *key, PyObject *v)

6373

+.. c:function:: int PyMapping_SetItemString(PyObject *o, char *key, PyObject *v)

6374

6375

Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure.

6376

This is the equivalent of the Python statement ``o[key] = v``.

6377

diff -r 8527427914a2 Doc/c-api/marshal.rst

6378

--- a/Doc/c-api/marshal.rst

6379

+++ b/Doc/c-api/marshal.rst

6380

@@ -20,17 +20,17 @@

6381

file format (currently 2).

6382

6383

6384

-.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)

6385

+.. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)

6386

6387

- Marshal a :ctype:`long` integer, *value*, to *file*. This will only write

6388

+ Marshal a :c:type:`long` integer, *value*, to *file*. This will only write

6389

the least-significant 32 bits of *value*; regardless of the size of the

6390

- native :ctype:`long` type.

6391

+ native :c:type:`long` type.

6392

6393

.. versionchanged:: 2.4

6394

*version* indicates the file format.

6395

6396

6397

-.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)

6398

+.. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)

6399

6400

Marshal a Python object, *value*, to *file*.

6401

6402

@@ -38,7 +38,7 @@

6403

*version* indicates the file format.

6404

6405

6406

-.. cfunction:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)

6407

+.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)

6408

6409

Return a string object containing the marshalled representation of *value*.

6410

6411

@@ -55,31 +55,31 @@

6412

written using these routines?

6413

6414

6415

-.. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)

6416

+.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)

6417

6418

- Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened

6419

+ Return a C :c:type:`long` from the data stream in a :c:type:`FILE\*` opened

6420

for reading. Only a 32-bit value can be read in using this function,

6421

- regardless of the native size of :ctype:`long`.

6422

+ regardless of the native size of :c:type:`long`.

6423

6424

6425

-.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)

6426

+.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)

6427

6428

- Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened

6429

+ Return a C :c:type:`short` from the data stream in a :c:type:`FILE\*` opened

6430

for reading. Only a 16-bit value can be read in using this function,

6431

- regardless of the native size of :ctype:`short`.

6432

+ regardless of the native size of :c:type:`short`.

6433

6434

6435

-.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)

6436

+.. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)

6437

6438

- Return a Python object from the data stream in a :ctype:`FILE\*` opened for

6439

+ Return a Python object from the data stream in a :c:type:`FILE\*` opened for

6440

reading. On error, sets the appropriate exception (:exc:`EOFError` or

6441

:exc:`TypeError`) and returns *NULL*.

6442

6443

6444

-.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)

6445

+.. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)

6446

6447

- Return a Python object from the data stream in a :ctype:`FILE\*` opened for

6448

- reading. Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function

6449

+ Return a Python object from the data stream in a :c:type:`FILE\*` opened for

6450

+ reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function

6451

assumes that no further objects will be read from the file, allowing it to

6452

aggressively load file data into memory so that the de-serialization can

6453

operate from data in memory rather than reading a byte at a time from the

6454

@@ -88,7 +88,7 @@

6455

(:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.

6456

6457

6458

-.. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)

6459

+.. c:function:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)

6460

6461

Return a Python object from the data stream in a character buffer

6462

containing *len* bytes pointed to by *string*. On error, sets the

6463

@@ -96,5 +96,5 @@

6464

*NULL*.

6465

6466

.. versionchanged:: 2.5

6467

- This function used an :ctype:`int` type for *len*. This might require

6468

+ This function used an :c:type:`int` type for *len*. This might require

6469

changes in your code for properly supporting 64-bit systems.

6470

diff -r 8527427914a2 Doc/c-api/memory.rst

6471

--- a/Doc/c-api/memory.rst

6472

+++ b/Doc/c-api/memory.rst

6473

@@ -47,8 +47,8 @@

6474

single: free()

6475

6476

To avoid memory corruption, extension writers should never try to operate on

6477

-Python objects with the functions exported by the C library: :cfunc:`malloc`,

6478

-:cfunc:`calloc`, :cfunc:`realloc` and :cfunc:`free`. This will result in mixed

6479

+Python objects with the functions exported by the C library: :c:func:`malloc`,

6480

+:c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. This will result in mixed

6481

calls between the C allocator and the Python memory manager with fatal

6482

consequences, because they implement different algorithms and operate on

6483

different heaps. However, one may safely allocate and release memory blocks

6484

@@ -94,65 +94,65 @@

6485

memory from the Python heap:

6486

6487

6488

-.. cfunction:: void* PyMem_Malloc(size_t n)

6489

+.. c:function:: void* PyMem_Malloc(size_t n)

6490

6491

- Allocates *n* bytes and returns a pointer of type :ctype:`void\*` to the

6492

+ Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the

6493

allocated memory, or *NULL* if the request fails. Requesting zero bytes returns

6494

- a distinct non-*NULL* pointer if possible, as if :cfunc:`PyMem_Malloc(1)` had

6495

+ a distinct non-*NULL* pointer if possible, as if :c:func:`PyMem_Malloc(1)` had

6496

been called instead. The memory will not have been initialized in any way.

6497

6498

6499

-.. cfunction:: void* PyMem_Realloc(void *p, size_t n)

6500

+.. c:function:: void* PyMem_Realloc(void *p, size_t n)

6501

6502

Resizes the memory block pointed to by *p* to *n* bytes. The contents will be

6503

unchanged to the minimum of the old and the new sizes. If *p* is *NULL*, the

6504

- call is equivalent to :cfunc:`PyMem_Malloc(n)`; else if *n* is equal to zero,

6505

+ call is equivalent to :c:func:`PyMem_Malloc(n)`; else if *n* is equal to zero,

6506

the memory block is resized but is not freed, and the returned pointer is

6507

non-*NULL*. Unless *p* is *NULL*, it must have been returned by a previous call

6508

- to :cfunc:`PyMem_Malloc` or :cfunc:`PyMem_Realloc`. If the request fails,

6509

- :cfunc:`PyMem_Realloc` returns *NULL* and *p* remains a valid pointer to the

6510

+ to :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. If the request fails,

6511

+ :c:func:`PyMem_Realloc` returns *NULL* and *p* remains a valid pointer to the

6512

previous memory area.

6513

6514

6515

-.. cfunction:: void PyMem_Free(void *p)

6516

+.. c:function:: void PyMem_Free(void *p)

6517

6518

Frees the memory block pointed to by *p*, which must have been returned by a

6519

- previous call to :cfunc:`PyMem_Malloc` or :cfunc:`PyMem_Realloc`. Otherwise, or

6520

- if :cfunc:`PyMem_Free(p)` has been called before, undefined behavior occurs. If

6521

+ previous call to :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. Otherwise, or

6522

+ if :c:func:`PyMem_Free(p)` has been called before, undefined behavior occurs. If

6523

*p* is *NULL*, no operation is performed.

6524

6525

The following type-oriented macros are provided for convenience. Note that

6526

*TYPE* refers to any C type.

6527

6528

6529

-.. cfunction:: TYPE* PyMem_New(TYPE, size_t n)

6530

+.. c:function:: TYPE* PyMem_New(TYPE, size_t n)

6531

6532

- Same as :cfunc:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of

6533

- memory. Returns a pointer cast to :ctype:`TYPE\*`. The memory will not have

6534

+ Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of

6535

+ memory. Returns a pointer cast to :c:type:`TYPE\*`. The memory will not have

6536

been initialized in any way.

6537

6538

6539

-.. cfunction:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)

6540

+.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)

6541

6542

- Same as :cfunc:`PyMem_Realloc`, but the memory block is resized to ``(n *

6543

- sizeof(TYPE))`` bytes. Returns a pointer cast to :ctype:`TYPE\*`. On return,

6544

+ Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *

6545

+ sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE\*`. On return,

6546

*p* will be a pointer to the new memory area, or *NULL* in the event of

6547

failure. This is a C preprocessor macro; p is always reassigned. Save

6548

the original value of p to avoid losing memory when handling errors.

6549

6550

6551

-.. cfunction:: void PyMem_Del(void *p)

6552

+.. c:function:: void PyMem_Del(void *p)

6553

6554

- Same as :cfunc:`PyMem_Free`.

6555

+ Same as :c:func:`PyMem_Free`.

6556

6557

In addition, the following macro sets are provided for calling the Python memory

6558

allocator directly, without involving the C API functions listed above. However,

6559

note that their use does not preserve binary compatibility across Python

6560

versions and is therefore deprecated in extension modules.

6561

6562

-:cfunc:`PyMem_MALLOC`, :cfunc:`PyMem_REALLOC`, :cfunc:`PyMem_FREE`.

6563

+:c:func:`PyMem_MALLOC`, :c:func:`PyMem_REALLOC`, :c:func:`PyMem_FREE`.

6564

6565

-:cfunc:`PyMem_NEW`, :cfunc:`PyMem_RESIZE`, :cfunc:`PyMem_DEL`.

6566

+:c:func:`PyMem_NEW`, :c:func:`PyMem_RESIZE`, :c:func:`PyMem_DEL`.

6567

6568

6569

.. _memoryexamples:

6570

@@ -201,8 +201,8 @@

6571

free(buf1); /* Fatal -- should be PyMem_Del() */

6572

6573

In addition to the functions aimed at handling raw memory blocks from the Python

6574

-heap, objects in Python are allocated and released with :cfunc:`PyObject_New`,

6575

-:cfunc:`PyObject_NewVar` and :cfunc:`PyObject_Del`.

6576

+heap, objects in Python are allocated and released with :c:func:`PyObject_New`,

6577

+:c:func:`PyObject_NewVar` and :c:func:`PyObject_Del`.

6578

6579

These will be explained in the next chapter on defining and implementing new

6580

object types in C.

6581

diff -r 8527427914a2 Doc/c-api/method.rst

6582

--- a/Doc/c-api/method.rst

6583

+++ b/Doc/c-api/method.rst

6584

@@ -10,21 +10,21 @@

6585

There are some useful functions that are useful for working with method objects.

6586

6587

6588

-.. cvar:: PyTypeObject PyMethod_Type

6589

+.. c:var:: PyTypeObject PyMethod_Type

6590

6591

.. index:: single: MethodType (in module types)

6592

6593

- This instance of :ctype:`PyTypeObject` represents the Python method type. This

6594

+ This instance of :c:type:`PyTypeObject` represents the Python method type. This

6595

is exposed to Python programs as ``types.MethodType``.

6596

6597

6598

-.. cfunction:: int PyMethod_Check(PyObject *o)

6599

+.. c:function:: int PyMethod_Check(PyObject *o)

6600

6601

- Return true if *o* is a method object (has type :cdata:`PyMethod_Type`). The

6602

+ Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). The

6603

parameter must not be *NULL*.

6604

6605

6606

-.. cfunction:: PyObject* PyMethod_New(PyObject *func, PyObject *self, PyObject *class)

6607

+.. c:function:: PyObject* PyMethod_New(PyObject *func, PyObject *self, PyObject *class)

6608

6609

Return a new method object, with *func* being any callable object; this is the

6610

function that will be called when the method is called. If this method should

6611

@@ -33,39 +33,39 @@

6612

class which provides the unbound method..

6613

6614

6615

-.. cfunction:: PyObject* PyMethod_Class(PyObject *meth)

6616

+.. c:function:: PyObject* PyMethod_Class(PyObject *meth)

6617

6618

Return the class object from which the method *meth* was created; if this was

6619

created from an instance, it will be the class of the instance.

6620

6621

6622

-.. cfunction:: PyObject* PyMethod_GET_CLASS(PyObject *meth)

6623

+.. c:function:: PyObject* PyMethod_GET_CLASS(PyObject *meth)

6624

6625

- Macro version of :cfunc:`PyMethod_Class` which avoids error checking.

6626

+ Macro version of :c:func:`PyMethod_Class` which avoids error checking.

6627

6628

6629

-.. cfunction:: PyObject* PyMethod_Function(PyObject *meth)

6630

+.. c:function:: PyObject* PyMethod_Function(PyObject *meth)

6631

6632

Return the function object associated with the method *meth*.

6633

6634

6635

-.. cfunction:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)

6636

+.. c:function:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)

6637

6638

- Macro version of :cfunc:`PyMethod_Function` which avoids error checking.

6639

+ Macro version of :c:func:`PyMethod_Function` which avoids error checking.

6640

6641

6642

-.. cfunction:: PyObject* PyMethod_Self(PyObject *meth)

6643

+.. c:function:: PyObject* PyMethod_Self(PyObject *meth)

6644

6645

Return the instance associated with the method *meth* if it is bound, otherwise

6646

return *NULL*.

6647

6648

6649

-.. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth)

6650

+.. c:function:: PyObject* PyMethod_GET_SELF(PyObject *meth)

6651

6652

- Macro version of :cfunc:`PyMethod_Self` which avoids error checking.

6653

+ Macro version of :c:func:`PyMethod_Self` which avoids error checking.

6654

6655

6656

-.. cfunction:: int PyMethod_ClearFreeList()

6657

+.. c:function:: int PyMethod_ClearFreeList()

6658

6659

Clear the free list. Return the total number of freed items.

6660

6661

diff -r 8527427914a2 Doc/c-api/module.rst

6662

--- a/Doc/c-api/module.rst

6663

+++ b/Doc/c-api/module.rst

6664

@@ -10,15 +10,15 @@

6665

There are only a few functions special to module objects.

6666

6667

6668

-.. cvar:: PyTypeObject PyModule_Type

6669

+.. c:var:: PyTypeObject PyModule_Type

6670

6671

.. index:: single: ModuleType (in module types)

6672

6673

- This instance of :ctype:`PyTypeObject` represents the Python module type. This

6674

+ This instance of :c:type:`PyTypeObject` represents the Python module type. This

6675

is exposed to Python programs as ``types.ModuleType``.

6676

6677

6678

-.. cfunction:: int PyModule_Check(PyObject *p)

6679

+.. c:function:: int PyModule_Check(PyObject *p)

6680

6681

Return true if *p* is a module object, or a subtype of a module object.

6682

6683

@@ -26,15 +26,15 @@

6684

Allowed subtypes to be accepted.

6685

6686

6687

-.. cfunction:: int PyModule_CheckExact(PyObject *p)

6688

+.. c:function:: int PyModule_CheckExact(PyObject *p)

6689

6690

Return true if *p* is a module object, but not a subtype of

6691

- :cdata:`PyModule_Type`.

6692

+ :c:data:`PyModule_Type`.

6693

6694

.. versionadded:: 2.2

6695

6696

6697

-.. cfunction:: PyObject* PyModule_New(const char *name)

6698

+.. c:function:: PyObject* PyModule_New(const char *name)

6699

6700

.. index::

6701

single: __name__ (module attribute)

6702

@@ -46,18 +46,18 @@

6703

the caller is responsible for providing a :attr:`__file__` attribute.

6704

6705

6706

-.. cfunction:: PyObject* PyModule_GetDict(PyObject *module)

6707

+.. c:function:: PyObject* PyModule_GetDict(PyObject *module)

6708

6709

.. index:: single: __dict__ (module attribute)

6710

6711

Return the dictionary object that implements *module*'s namespace; this object

6712

is the same as the :attr:`__dict__` attribute of the module object. This

6713

function never fails. It is recommended extensions use other

6714

- :cfunc:`PyModule_\*` and :cfunc:`PyObject_\*` functions rather than directly

6715

+ :c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly

6716

manipulate a module's :attr:`__dict__`.

6717

6718

6719

-.. cfunction:: char* PyModule_GetName(PyObject *module)

6720

+.. c:function:: char* PyModule_GetName(PyObject *module)

6721

6722

.. index::

6723

single: __name__ (module attribute)

6724

@@ -67,7 +67,7 @@

6725

or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.

6726

6727

6728

-.. cfunction:: char* PyModule_GetFilename(PyObject *module)

6729

+.. c:function:: char* PyModule_GetFilename(PyObject *module)

6730

6731

.. index::

6732

single: __file__ (module attribute)

6733

@@ -78,7 +78,7 @@

6734

raise :exc:`SystemError` and return *NULL*.

6735

6736

6737

-.. cfunction:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)

6738

+.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)

6739

6740

Add an object to *module* as *name*. This is a convenience function which can

6741

be used from the module's initialization function. This steals a reference to

6742

@@ -87,7 +87,7 @@

6743

.. versionadded:: 2.0

6744

6745

6746

-.. cfunction:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

6747

+.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

6748

6749

Add an integer constant to *module* as *name*. This convenience function can be

6750

used from the module's initialization function. Return ``-1`` on error, ``0`` on

6751

@@ -96,7 +96,7 @@

6752

.. versionadded:: 2.0

6753

6754

6755

-.. cfunction:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)

6756

+.. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)

6757

6758

Add a string constant to *module* as *name*. This convenience function can be

6759

used from the module's initialization function. The string *value* must be

6760

@@ -104,7 +104,7 @@

6761

6762

.. versionadded:: 2.0

6763

6764

-.. cfunction:: int PyModule_AddIntMacro(PyObject *module, macro)

6765

+.. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)

6766

6767

Add an int constant to *module*. The name and the value are taken from

6768

*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int

6769

@@ -113,7 +113,7 @@

6770

6771

.. versionadded:: 2.6

6772

6773

-.. cfunction:: int PyModule_AddStringMacro(PyObject *module, macro)

6774

+.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)

6775

6776

Add a string constant to *module*.

6777

6778

diff -r 8527427914a2 Doc/c-api/none.rst

6779

--- a/Doc/c-api/none.rst

6780

+++ b/Doc/c-api/none.rst

6781

@@ -7,22 +7,22 @@

6782

6783

.. index:: object: None

6784

6785

-Note that the :ctype:`PyTypeObject` for ``None`` is not directly exposed in the

6786

+Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in the

6787

Python/C API. Since ``None`` is a singleton, testing for object identity (using

6788

-``==`` in C) is sufficient. There is no :cfunc:`PyNone_Check` function for the

6789

+``==`` in C) is sufficient. There is no :c:func:`PyNone_Check` function for the

6790

same reason.

6791

6792

6793

-.. cvar:: PyObject* Py_None

6794

+.. c:var:: PyObject* Py_None

6795

6796

The Python ``None`` object, denoting lack of value. This object has no methods.

6797

It needs to be treated just like any other object with respect to reference

6798

counts.

6799

6800

6801

-.. cmacro:: Py_RETURN_NONE

6802

+.. c:macro:: Py_RETURN_NONE

6803

6804

- Properly handle returning :cdata:`Py_None` from within a C function.

6805

+ Properly handle returning :c:data:`Py_None` from within a C function.

6806

6807

.. versionadded:: 2.4

6808

6809

diff -r 8527427914a2 Doc/c-api/number.rst

6810

--- a/Doc/c-api/number.rst

6811

+++ b/Doc/c-api/number.rst

6812

@@ -6,37 +6,37 @@

6813

===============

6814

6815

6816

-.. cfunction:: int PyNumber_Check(PyObject *o)

6817

+.. c:function:: int PyNumber_Check(PyObject *o)

6818

6819

Returns ``1`` if the object *o* provides numeric protocols, and false otherwise.

6820

This function always succeeds.

6821

6822

6823

-.. cfunction:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)

6824

+.. c:function:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)

6825

6826

Returns the result of adding *o1* and *o2*, or *NULL* on failure. This is the

6827

equivalent of the Python expression ``o1 + o2``.

6828

6829

6830

-.. cfunction:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)

6831

+.. c:function:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)

6832

6833

Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. This is

6834

the equivalent of the Python expression ``o1 - o2``.

6835

6836

6837

-.. cfunction:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)

6838

+.. c:function:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)

6839

6840

Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. This is

6841

the equivalent of the Python expression ``o1 * o2``.

6842

6843

6844

-.. cfunction:: PyObject* PyNumber_Divide(PyObject *o1, PyObject *o2)

6845

+.. c:function:: PyObject* PyNumber_Divide(PyObject *o1, PyObject *o2)

6846

6847

Returns the result of dividing *o1* by *o2*, or *NULL* on failure. This is the

6848

equivalent of the Python expression ``o1 / o2``.

6849

6850

6851

-.. cfunction:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)

6852

+.. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)

6853

6854

Return the floor of *o1* divided by *o2*, or *NULL* on failure. This is

6855

equivalent to the "classic" division of integers.

6856

@@ -44,7 +44,7 @@

6857

.. versionadded:: 2.2

6858

6859

6860

-.. cfunction:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)

6861

+.. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)

6862

6863

Return a reasonable approximation for the mathematical value of *o1* divided by

6864

*o2*, or *NULL* on failure. The return value is "approximate" because binary

6865

@@ -55,13 +55,13 @@

6866

.. versionadded:: 2.2

6867

6868

6869

-.. cfunction:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)

6870

+.. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)

6871

6872

Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. This is

6873

the equivalent of the Python expression ``o1 % o2``.

6874

6875

6876

-.. cfunction:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)

6877

+.. c:function:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)

6878

6879

.. index:: builtin: divmod

6880

6881

@@ -69,29 +69,29 @@

6882

the equivalent of the Python expression ``divmod(o1, o2)``.

6883

6884

6885

-.. cfunction:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)

6886

+.. c:function:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)

6887

6888

.. index:: builtin: pow

6889

6890

See the built-in function :func:`pow`. Returns *NULL* on failure. This is the

6891

equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.

6892

- If *o3* is to be ignored, pass :cdata:`Py_None` in its place (passing *NULL* for

6893

+ If *o3* is to be ignored, pass :c:data:`Py_None` in its place (passing *NULL* for

6894

*o3* would cause an illegal memory access).

6895

6896

6897

-.. cfunction:: PyObject* PyNumber_Negative(PyObject *o)

6898

+.. c:function:: PyObject* PyNumber_Negative(PyObject *o)

6899

6900

Returns the negation of *o* on success, or *NULL* on failure. This is the

6901

equivalent of the Python expression ``-o``.

6902

6903

6904

-.. cfunction:: PyObject* PyNumber_Positive(PyObject *o)

6905

+.. c:function:: PyObject* PyNumber_Positive(PyObject *o)

6906

6907

Returns *o* on success, or *NULL* on failure. This is the equivalent of the

6908

Python expression ``+o``.

6909

6910

6911

-.. cfunction:: PyObject* PyNumber_Absolute(PyObject *o)

6912

+.. c:function:: PyObject* PyNumber_Absolute(PyObject *o)

6913

6914

.. index:: builtin: abs

6915

6916

@@ -99,71 +99,71 @@

6917

of the Python expression ``abs(o)``.

6918

6919

6920

-.. cfunction:: PyObject* PyNumber_Invert(PyObject *o)

6921

+.. c:function:: PyObject* PyNumber_Invert(PyObject *o)

6922

6923

Returns the bitwise negation of *o* on success, or *NULL* on failure. This is

6924

the equivalent of the Python expression ``~o``.

6925

6926

6927

-.. cfunction:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)

6928

+.. c:function:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)

6929

6930

Returns the result of left shifting *o1* by *o2* on success, or *NULL* on

6931

failure. This is the equivalent of the Python expression ``o1 << o2``.

6932

6933

6934

-.. cfunction:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)

6935

+.. c:function:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)

6936

6937

Returns the result of right shifting *o1* by *o2* on success, or *NULL* on

6938

failure. This is the equivalent of the Python expression ``o1 >> o2``.

6939

6940

6941

-.. cfunction:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)

6942

+.. c:function:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)

6943

6944

Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure.

6945

This is the equivalent of the Python expression ``o1 & o2``.

6946

6947

6948

-.. cfunction:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)

6949

+.. c:function:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)

6950

6951

Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on

6952

failure. This is the equivalent of the Python expression ``o1 ^ o2``.

6953

6954

6955

-.. cfunction:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)

6956

+.. c:function:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)

6957

6958

Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.

6959

This is the equivalent of the Python expression ``o1 | o2``.

6960

6961

6962

-.. cfunction:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)

6963

+.. c:function:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)

6964

6965

Returns the result of adding *o1* and *o2*, or *NULL* on failure. The operation

6966

is done *in-place* when *o1* supports it. This is the equivalent of the Python

6967

statement ``o1 += o2``.

6968

6969

6970

-.. cfunction:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)

6971

+.. c:function:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)

6972

6973

Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. The

6974

operation is done *in-place* when *o1* supports it. This is the equivalent of

6975

the Python statement ``o1 -= o2``.

6976

6977

6978

-.. cfunction:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)

6979

+.. c:function:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)

6980

6981

Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. The

6982

operation is done *in-place* when *o1* supports it. This is the equivalent of

6983

the Python statement ``o1 *= o2``.

6984

6985

6986

-.. cfunction:: PyObject* PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2)

6987

+.. c:function:: PyObject* PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2)

6988

6989

Returns the result of dividing *o1* by *o2*, or *NULL* on failure. The

6990

operation is done *in-place* when *o1* supports it. This is the equivalent of

6991

the Python statement ``o1 /= o2``.

6992

6993

6994

-.. cfunction:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)

6995

+.. c:function:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)

6996

6997

Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure.

6998

The operation is done *in-place* when *o1* supports it. This is the equivalent

6999

@@ -172,7 +172,7 @@

7000

.. versionadded:: 2.2

7001

7002

7003

-.. cfunction:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)

7004

+.. c:function:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)

7005

7006

Return a reasonable approximation for the mathematical value of *o1* divided by

7007

*o2*, or *NULL* on failure. The return value is "approximate" because binary

7008

@@ -183,64 +183,64 @@

7009

.. versionadded:: 2.2

7010

7011

7012

-.. cfunction:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)

7013

+.. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)

7014

7015

Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. The

7016

operation is done *in-place* when *o1* supports it. This is the equivalent of

7017

the Python statement ``o1 %= o2``.

7018

7019

7020

-.. cfunction:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)

7021

+.. c:function:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)

7022

7023

.. index:: builtin: pow

7024

7025

See the built-in function :func:`pow`. Returns *NULL* on failure. The operation

7026

is done *in-place* when *o1* supports it. This is the equivalent of the Python

7027

- statement ``o1 **= o2`` when o3 is :cdata:`Py_None`, or an in-place variant of

7028

- ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :cdata:`Py_None`

7029

+ statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-place variant of

7030

+ ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :c:data:`Py_None`

7031

in its place (passing *NULL* for *o3* would cause an illegal memory access).

7032

7033

7034

-.. cfunction:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)

7035

+.. c:function:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)

7036

7037

Returns the result of left shifting *o1* by *o2* on success, or *NULL* on

7038

failure. The operation is done *in-place* when *o1* supports it. This is the

7039

equivalent of the Python statement ``o1 <<= o2``.

7040

7041

7042

-.. cfunction:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)

7043

+.. c:function:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)

7044

7045

Returns the result of right shifting *o1* by *o2* on success, or *NULL* on

7046

failure. The operation is done *in-place* when *o1* supports it. This is the

7047

equivalent of the Python statement ``o1 >>= o2``.

7048

7049

7050

-.. cfunction:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)

7051

+.. c:function:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)

7052

7053

Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. The

7054

operation is done *in-place* when *o1* supports it. This is the equivalent of

7055

the Python statement ``o1 &= o2``.

7056

7057

7058

-.. cfunction:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)

7059

+.. c:function:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)

7060

7061

Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on

7062

failure. The operation is done *in-place* when *o1* supports it. This is the

7063

equivalent of the Python statement ``o1 ^= o2``.

7064

7065

7066

-.. cfunction:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)

7067

+.. c:function:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)

7068

7069

Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure. The

7070

operation is done *in-place* when *o1* supports it. This is the equivalent of

7071

the Python statement ``o1 |= o2``.

7072

7073

7074

-.. cfunction:: int PyNumber_Coerce(PyObject **p1, PyObject **p2)

7075

+.. c:function:: int PyNumber_Coerce(PyObject **p1, PyObject **p2)

7076

7077

.. index:: builtin: coerce

7078

7079

- This function takes the addresses of two variables of type :ctype:`PyObject\*`.

7080

+ This function takes the addresses of two variables of type :c:type:`PyObject\*`.

7081

If the objects pointed to by ``*p1`` and ``*p2`` have the same type, increment

7082

their reference count and return ``0`` (success). If the objects can be

7083

converted to a common numeric type, replace ``*p1`` and ``*p2`` by their

7084

@@ -250,14 +250,14 @@

7085

&o2)`` is equivalent to the Python statement ``o1, o2 = coerce(o1, o2)``.

7086

7087

7088

-.. cfunction:: int PyNumber_CoerceEx(PyObject **p1, PyObject **p2)

7089

+.. c:function:: int PyNumber_CoerceEx(PyObject **p1, PyObject **p2)

7090

7091

- This function is similar to :cfunc:`PyNumber_Coerce`, except that it returns

7092

+ This function is similar to :c:func:`PyNumber_Coerce`, except that it returns

7093

``1`` when the conversion is not possible and when no error is raised.

7094

Reference counts are still not increased in this case.

7095

7096

7097

-.. cfunction:: PyObject* PyNumber_Int(PyObject *o)

7098

+.. c:function:: PyObject* PyNumber_Int(PyObject *o)

7099

7100

.. index:: builtin: int

7101

7102

@@ -266,7 +266,7 @@

7103

instead. This is the equivalent of the Python expression ``int(o)``.

7104

7105

7106

-.. cfunction:: PyObject* PyNumber_Long(PyObject *o)

7107

+.. c:function:: PyObject* PyNumber_Long(PyObject *o)

7108

7109

.. index:: builtin: long

7110

7111

@@ -274,7 +274,7 @@

7112

failure. This is the equivalent of the Python expression ``long(o)``.

7113

7114

7115

-.. cfunction:: PyObject* PyNumber_Float(PyObject *o)

7116

+.. c:function:: PyObject* PyNumber_Float(PyObject *o)

7117

7118

.. index:: builtin: float

7119

7120

@@ -282,7 +282,7 @@

7121

This is the equivalent of the Python expression ``float(o)``.

7122

7123

7124

-.. cfunction:: PyObject* PyNumber_Index(PyObject *o)

7125

+.. c:function:: PyObject* PyNumber_Index(PyObject *o)

7126

7127

Returns the *o* converted to a Python int or long on success or *NULL* with a

7128

:exc:`TypeError` exception raised on failure.

7129

@@ -290,18 +290,18 @@

7130

.. versionadded:: 2.5

7131

7132

7133

-.. cfunction:: PyObject* PyNumber_ToBase(PyObject *n, int base)

7134

+.. c:function:: PyObject* PyNumber_ToBase(PyObject *n, int base)

7135

7136

Returns the integer *n* converted to *base* as a string with a base

7137

marker of ``'0b'``, ``'0o'``, or ``'0x'`` if applicable. When

7138

*base* is not 2, 8, 10, or 16, the format is ``'x#num'`` where x is the

7139

base. If *n* is not an int object, it is converted with

7140

- :cfunc:`PyNumber_Index` first.

7141

+ :c:func:`PyNumber_Index` first.

7142

7143

.. versionadded:: 2.6

7144

7145

7146

-.. cfunction:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)

7147

+.. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)

7148

7149

Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an

7150

integer. If *o* can be converted to a Python int or long but the attempt to

7151

@@ -314,7 +314,7 @@

7152

.. versionadded:: 2.5

7153

7154

7155

-.. cfunction:: int PyIndex_Check(PyObject *o)

7156

+.. c:function:: int PyIndex_Check(PyObject *o)

7157

7158

Returns True if *o* is an index integer (has the nb_index slot of the

7159

tp_as_number structure filled in).

7160

diff -r 8527427914a2 Doc/c-api/objbuffer.rst

7161

--- a/Doc/c-api/objbuffer.rst

7162

+++ b/Doc/c-api/objbuffer.rst

7163

@@ -13,7 +13,7 @@

7164

:ref:`bufferobjects` for more information.

7165

7166

7167

-.. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)

7168

+.. c:function:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)

7169

7170

Returns a pointer to a read-only memory location usable as character-based

7171

input. The *obj* argument must support the single-segment character buffer

7172

@@ -24,11 +24,11 @@

7173

.. versionadded:: 1.6

7174

7175

.. versionchanged:: 2.5

7176

- This function used an :ctype:`int *` type for *buffer_len*. This might

7177

+ This function used an :c:type:`int *` type for *buffer_len*. This might

7178

require changes in your code for properly supporting 64-bit systems.

7179

7180

7181

-.. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)

7182

+.. c:function:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)

7183

7184

Returns a pointer to a read-only memory location containing arbitrary data.

7185

The *obj* argument must support the single-segment readable buffer

7186

@@ -39,11 +39,11 @@

7187

.. versionadded:: 1.6

7188

7189

.. versionchanged:: 2.5

7190

- This function used an :ctype:`int *` type for *buffer_len*. This might

7191

+ This function used an :c:type:`int *` type for *buffer_len*. This might

7192

require changes in your code for properly supporting 64-bit systems.

7193

7194

7195

-.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)

7196

+.. c:function:: int PyObject_CheckReadBuffer(PyObject *o)

7197

7198

Returns ``1`` if *o* supports the single-segment readable buffer interface.

7199

Otherwise returns ``0``.

7200

@@ -51,7 +51,7 @@

7201

.. versionadded:: 2.2

7202

7203

7204

-.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)

7205

+.. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)

7206

7207

Returns a pointer to a writeable memory location. The *obj* argument must

7208

support the single-segment, character buffer interface. On success,

7209

@@ -61,6 +61,6 @@

7210

.. versionadded:: 1.6

7211

7212

.. versionchanged:: 2.5

7213

- This function used an :ctype:`int *` type for *buffer_len*. This might

7214

+ This function used an :c:type:`int *` type for *buffer_len*. This might

7215

require changes in your code for properly supporting 64-bit systems.

7216

7217

diff -r 8527427914a2 Doc/c-api/object.rst

7218

--- a/Doc/c-api/object.rst

7219

+++ b/Doc/c-api/object.rst

7220

@@ -6,7 +6,7 @@

7221

===============

7222

7223

7224

-.. cfunction:: int PyObject_Print(PyObject *o, FILE *fp, int flags)

7225

+.. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)

7226

7227

Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument

7228

is used to enable certain printing options. The only option currently supported

7229

@@ -14,35 +14,35 @@

7230

instead of the :func:`repr`.

7231

7232

7233

-.. cfunction:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

7234

+.. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

7235

7236

Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This

7237

is equivalent to the Python expression ``hasattr(o, attr_name)``. This function

7238

always succeeds.

7239

7240

7241

-.. cfunction:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)

7242

+.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)

7243

7244

Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This

7245

is equivalent to the Python expression ``hasattr(o, attr_name)``. This function

7246

always succeeds.

7247

7248

7249

-.. cfunction:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)

7250

+.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)

7251

7252

Retrieve an attribute named *attr_name* from object *o*. Returns the attribute

7253

value on success, or *NULL* on failure. This is the equivalent of the Python

7254

expression ``o.attr_name``.

7255

7256

7257

-.. cfunction:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)

7258

+.. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)

7259

7260

Retrieve an attribute named *attr_name* from object *o*. Returns the attribute

7261

value on success, or *NULL* on failure. This is the equivalent of the Python

7262

expression ``o.attr_name``.

7263

7264

7265

-.. cfunction:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)

7266

+.. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)

7267

7268

Generic attribute getter function that is meant to be put into a type

7269

object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary

7270

@@ -52,21 +52,21 @@

7271

descriptors don't. Otherwise, an :exc:`AttributeError` is raised.

7272

7273

7274

-.. cfunction:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)

7275

+.. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)

7276

7277

Set the value of the attribute named *attr_name*, for object *o*, to the value

7278

*v*. Returns ``-1`` on failure. This is the equivalent of the Python statement

7279

``o.attr_name = v``.

7280

7281

7282

-.. cfunction:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)

7283

+.. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)

7284

7285

Set the value of the attribute named *attr_name*, for object *o*, to the value

7286

*v*. Returns ``-1`` on failure. This is the equivalent of the Python statement

7287

``o.attr_name = v``.

7288

7289

7290

-.. cfunction:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)

7291

+.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)

7292

7293

Generic attribute setter function that is meant to be put into a type

7294

object's ``tp_setattro`` slot. It looks for a data descriptor in the

7295

@@ -76,19 +76,19 @@

7296

an :exc:`AttributeError` is raised and ``-1`` is returned.

7297

7298

7299

-.. cfunction:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)

7300

+.. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)

7301

7302

Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.

7303

This is the equivalent of the Python statement ``del o.attr_name``.

7304

7305

7306

-.. cfunction:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)

7307

+.. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)

7308

7309

Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.

7310

This is the equivalent of the Python statement ``del o.attr_name``.

7311

7312

7313

-.. cfunction:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)

7314

+.. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)

7315

7316

Compare the values of *o1* and *o2* using the operation specified by *opid*,

7317

which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,

7318

@@ -98,7 +98,7 @@

7319

to *opid*. Returns the value of the comparison on success, or *NULL* on failure.

7320

7321

7322

-.. cfunction:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)

7323

+.. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)

7324

7325

Compare the values of *o1* and *o2* using the operation specified by *opid*,

7326

which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,

7327

@@ -109,10 +109,10 @@

7328

*opid*.

7329

7330

.. note::

7331

- If *o1* and *o2* are the same object, :cfunc:`PyObject_RichCompareBool`

7332

+ If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`

7333

will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`.

7334

7335

-.. cfunction:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)

7336

+.. c:function:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)

7337

7338

.. index:: builtin: cmp

7339

7340

@@ -122,18 +122,18 @@

7341

the Python statement ``result = cmp(o1, o2)``.

7342

7343

7344

-.. cfunction:: int PyObject_Compare(PyObject *o1, PyObject *o2)

7345

+.. c:function:: int PyObject_Compare(PyObject *o1, PyObject *o2)

7346

7347

.. index:: builtin: cmp

7348

7349

Compare the values of *o1* and *o2* using a routine provided by *o1*, if one

7350

exists, otherwise with a routine provided by *o2*. Returns the result of the

7351

comparison on success. On error, the value returned is undefined; use

7352

- :cfunc:`PyErr_Occurred` to detect an error. This is equivalent to the Python

7353

+ :c:func:`PyErr_Occurred` to detect an error. This is equivalent to the Python

7354

expression ``cmp(o1, o2)``.

7355

7356

7357

-.. cfunction:: PyObject* PyObject_Repr(PyObject *o)

7358

+.. c:function:: PyObject* PyObject_Repr(PyObject *o)

7359

7360

.. index:: builtin: repr

7361

7362

@@ -143,7 +143,7 @@

7363

by reverse quotes.

7364

7365

7366

-.. cfunction:: PyObject* PyObject_Str(PyObject *o)

7367

+.. c:function:: PyObject* PyObject_Str(PyObject *o)

7368

7369

.. index:: builtin: str

7370

7371

@@ -153,15 +153,15 @@

7372

by the :keyword:`print` statement.

7373

7374

7375

-.. cfunction:: PyObject* PyObject_Bytes(PyObject *o)

7376

+.. c:function:: PyObject* PyObject_Bytes(PyObject *o)

7377

7378

.. index:: builtin: bytes

7379

7380

Compute a bytes representation of object *o*. In 2.x, this is just a alias

7381

- for :cfunc:`PyObject_Str`.

7382

+ for :c:func:`PyObject_Str`.

7383

7384

7385

-.. cfunction:: PyObject* PyObject_Unicode(PyObject *o)

7386

+.. c:function:: PyObject* PyObject_Unicode(PyObject *o)

7387

7388

.. index:: builtin: unicode

7389

7390

@@ -171,11 +171,11 @@

7391

function.

7392

7393

7394

-.. cfunction:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)

7395

+.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)

7396

7397

Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of

7398

*cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. If

7399

- *cls* is a type object rather than a class object, :cfunc:`PyObject_IsInstance`

7400

+ *cls* is a type object rather than a class object, :c:func:`PyObject_IsInstance`

7401

returns ``1`` if *inst* is of type *cls*. If *cls* is a tuple, the check will

7402

be done against every entry in *cls*. The result will be ``1`` when at least one

7403

of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a

7404

@@ -195,13 +195,13 @@

7405

:class:`A` if it inherits from :class:`A` either directly or indirectly. If

7406

either is not a class object, a more general mechanism is used to determine the

7407

class relationship of the two objects. When testing if *B* is a subclass of

7408

-*A*, if *A* is *B*, :cfunc:`PyObject_IsSubclass` returns true. If *A* and *B*

7409

+*A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true. If *A* and *B*

7410

are different objects, *B*'s :attr:`__bases__` attribute is searched in a

7411

depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute

7412

is considered sufficient for this determination.

7413

7414

7415

-.. cfunction:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)

7416

+.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)

7417

7418

Returns ``1`` if the class *derived* is identical to or derived from the class

7419

*cls*, otherwise returns ``0``. In case of an error, returns ``-1``. If *cls*

7420

@@ -216,13 +216,13 @@

7421

Older versions of Python did not support a tuple as the second argument.

7422

7423

7424

-.. cfunction:: int PyCallable_Check(PyObject *o)

7425

+.. c:function:: int PyCallable_Check(PyObject *o)

7426

7427

Determine if the object *o* is callable. Return ``1`` if the object is callable

7428

and ``0`` otherwise. This function always succeeds.

7429

7430

7431

-.. cfunction:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)

7432

+.. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)

7433

7434

.. index:: builtin: apply

7435

7436

@@ -236,7 +236,7 @@

7437

.. versionadded:: 2.2

7438

7439

7440

-.. cfunction:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)

7441

+.. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)

7442

7443

.. index:: builtin: apply

7444

7445

@@ -247,52 +247,52 @@

7446

``callable_object(*args)``.

7447

7448

7449

-.. cfunction:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)

7450

+.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)

7451

7452

.. index:: builtin: apply

7453

7454

Call a callable Python object *callable*, with a variable number of C arguments.

7455

- The C arguments are described using a :cfunc:`Py_BuildValue` style format

7456

+ The C arguments are described using a :c:func:`Py_BuildValue` style format

7457

string. The format may be *NULL*, indicating that no arguments are provided.

7458

Returns the result of the call on success, or *NULL* on failure. This is the

7459

equivalent of the Python expression ``apply(callable, args)`` or

7460

- ``callable(*args)``. Note that if you only pass :ctype:`PyObject \*` args,

7461

- :cfunc:`PyObject_CallFunctionObjArgs` is a faster alternative.

7462

+ ``callable(*args)``. Note that if you only pass :c:type:`PyObject \*` args,

7463

+ :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.

7464

7465

7466

-.. cfunction:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)

7467

+.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)

7468

7469

Call the method named *method* of object *o* with a variable number of C

7470

- arguments. The C arguments are described by a :cfunc:`Py_BuildValue` format

7471

+ arguments. The C arguments are described by a :c:func:`Py_BuildValue` format

7472

string that should produce a tuple. The format may be *NULL*, indicating that

7473

no arguments are provided. Returns the result of the call on success, or *NULL*

7474

on failure. This is the equivalent of the Python expression ``o.method(args)``.

7475

- Note that if you only pass :ctype:`PyObject \*` args,

7476

- :cfunc:`PyObject_CallMethodObjArgs` is a faster alternative.

7477

+ Note that if you only pass :c:type:`PyObject \*` args,

7478

+ :c:func:`PyObject_CallMethodObjArgs` is a faster alternative.

7479

7480

7481

-.. cfunction:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)

7482

+.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)

7483

7484

Call a callable Python object *callable*, with a variable number of

7485

- :ctype:`PyObject\*` arguments. The arguments are provided as a variable number

7486

+ :c:type:`PyObject\*` arguments. The arguments are provided as a variable number

7487

of parameters followed by *NULL*. Returns the result of the call on success, or

7488

*NULL* on failure.

7489

7490

.. versionadded:: 2.2

7491

7492

7493

-.. cfunction:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)

7494

+.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)

7495

7496

Calls a method of the object *o*, where the name of the method is given as a

7497

Python string object in *name*. It is called with a variable number of

7498

- :ctype:`PyObject\*` arguments. The arguments are provided as a variable number

7499

+ :c:type:`PyObject\*` arguments. The arguments are provided as a variable number

7500

of parameters followed by *NULL*. Returns the result of the call on success, or

7501

*NULL* on failure.

7502

7503

.. versionadded:: 2.2

7504

7505

7506

-.. cfunction:: long PyObject_Hash(PyObject *o)

7507

+.. c:function:: long PyObject_Hash(PyObject *o)

7508

7509

.. index:: builtin: hash

7510

7511

@@ -300,7 +300,7 @@

7512

This is the equivalent of the Python expression ``hash(o)``.

7513

7514

7515

-.. cfunction:: long PyObject_HashNotImplemented(PyObject *o)

7516

+.. c:function:: long PyObject_HashNotImplemented(PyObject *o)

7517

7518

Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``.

7519

This function receives special treatment when stored in a ``tp_hash`` slot,

7520

@@ -310,21 +310,21 @@

7521

.. versionadded:: 2.6

7522

7523

7524

-.. cfunction:: int PyObject_IsTrue(PyObject *o)

7525

+.. c:function:: int PyObject_IsTrue(PyObject *o)

7526

7527

Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.

7528

This is equivalent to the Python expression ``not not o``. On failure, return

7529

``-1``.

7530

7531

7532

-.. cfunction:: int PyObject_Not(PyObject *o)

7533

+.. c:function:: int PyObject_Not(PyObject *o)

7534

7535

Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.

7536

This is equivalent to the Python expression ``not o``. On failure, return

7537

``-1``.

7538

7539

7540

-.. cfunction:: PyObject* PyObject_Type(PyObject *o)

7541

+.. c:function:: PyObject* PyObject_Type(PyObject *o)

7542

7543

.. index:: builtin: type

7544

7545

@@ -333,11 +333,11 @@

7546

is equivalent to the Python expression ``type(o)``. This function increments the

7547

reference count of the return value. There's really no reason to use this

7548

function instead of the common expression ``o->ob_type``, which returns a

7549

- pointer of type :ctype:`PyTypeObject\*`, except when the incremented reference

7550

+ pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference

7551

count is needed.

7552

7553

7554

-.. cfunction:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

7555

+.. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

7556

7557

Return true if the object *o* is of type *type* or a subtype of *type*. Both

7558

parameters must be non-*NULL*.

7559

@@ -345,7 +345,7 @@

7560

.. versionadded:: 2.2

7561

7562

7563

-.. cfunction:: Py_ssize_t PyObject_Length(PyObject *o)

7564

+.. c:function:: Py_ssize_t PyObject_Length(PyObject *o)

7565

Py_ssize_t PyObject_Size(PyObject *o)

7566

7567

.. index:: builtin: len

7568

@@ -355,29 +355,29 @@

7569

returned. This is the equivalent to the Python expression ``len(o)``.

7570

7571

.. versionchanged:: 2.5

7572

- These functions returned an :ctype:`int` type. This might require

7573

+ These functions returned an :c:type:`int` type. This might require

7574

changes in your code for properly supporting 64-bit systems.

7575

7576

7577

-.. cfunction:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)

7578

+.. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)

7579

7580

Return element of *o* corresponding to the object *key* or *NULL* on failure.

7581

This is the equivalent of the Python expression ``o[key]``.

7582

7583

7584

-.. cfunction:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)

7585

+.. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)

7586

7587

Map the object *key* to the value *v*. Returns ``-1`` on failure. This is the

7588

equivalent of the Python statement ``o[key] = v``.

7589

7590

7591

-.. cfunction:: int PyObject_DelItem(PyObject *o, PyObject *key)

7592

+.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)

7593

7594

Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the

7595

equivalent of the Python statement ``del o[key]``.

7596

7597

7598

-.. cfunction:: int PyObject_AsFileDescriptor(PyObject *o)

7599

+.. c:function:: int PyObject_AsFileDescriptor(PyObject *o)

7600

7601

Derives a file descriptor from a Python object. If the object is an integer or

7602

long integer, its value is returned. If not, the object's :meth:`fileno` method

7603

@@ -385,16 +385,16 @@

7604

is returned as the file descriptor value. Returns ``-1`` on failure.

7605

7606

7607

-.. cfunction:: PyObject* PyObject_Dir(PyObject *o)

7608

+.. c:function:: PyObject* PyObject_Dir(PyObject *o)

7609

7610

This is equivalent to the Python expression ``dir(o)``, returning a (possibly

7611

empty) list of strings appropriate for the object argument, or *NULL* if there

7612

was an error. If the argument is *NULL*, this is like the Python ``dir()``,

7613

returning the names of the current locals; in this case, if no execution frame

7614

- is active then *NULL* is returned but :cfunc:`PyErr_Occurred` will return false.

7615

+ is active then *NULL* is returned but :c:func:`PyErr_Occurred` will return false.

7616

7617

7618

-.. cfunction:: PyObject* PyObject_GetIter(PyObject *o)

7619

+.. c:function:: PyObject* PyObject_GetIter(PyObject *o)

7620

7621

This is equivalent to the Python expression ``iter(o)``. It returns a new

7622

iterator for the object argument, or the object itself if the object is already

7623

diff -r 8527427914a2 Doc/c-api/refcounting.rst

7624

--- a/Doc/c-api/refcounting.rst

7625

+++ b/Doc/c-api/refcounting.rst

7626

@@ -11,22 +11,22 @@

7627

objects.

7628

7629

7630

-.. cfunction:: void Py_INCREF(PyObject *o)

7631

+.. c:function:: void Py_INCREF(PyObject *o)

7632

7633

Increment the reference count for object *o*. The object must not be *NULL*; if

7634

- you aren't sure that it isn't *NULL*, use :cfunc:`Py_XINCREF`.

7635

+ you aren't sure that it isn't *NULL*, use :c:func:`Py_XINCREF`.

7636

7637

7638

-.. cfunction:: void Py_XINCREF(PyObject *o)

7639

+.. c:function:: void Py_XINCREF(PyObject *o)

7640

7641

Increment the reference count for object *o*. The object may be *NULL*, in

7642

which case the macro has no effect.

7643

7644

7645

-.. cfunction:: void Py_DECREF(PyObject *o)

7646

+.. c:function:: void Py_DECREF(PyObject *o)

7647

7648

Decrement the reference count for object *o*. The object must not be *NULL*; if

7649

- you aren't sure that it isn't *NULL*, use :cfunc:`Py_XDECREF`. If the reference

7650

+ you aren't sure that it isn't *NULL*, use :c:func:`Py_XDECREF`. If the reference

7651

count reaches zero, the object's type's deallocation function (which must not be

7652

*NULL*) is invoked.

7653

7654

@@ -36,25 +36,25 @@

7655

when a class instance with a :meth:`__del__` method is deallocated). While

7656

exceptions in such code are not propagated, the executed code has free access to

7657

all Python global variables. This means that any object that is reachable from

7658

- a global variable should be in a consistent state before :cfunc:`Py_DECREF` is

7659

+ a global variable should be in a consistent state before :c:func:`Py_DECREF` is

7660

invoked. For example, code to delete an object from a list should copy a

7661

reference to the deleted object in a temporary variable, update the list data

7662

- structure, and then call :cfunc:`Py_DECREF` for the temporary variable.

7663

+ structure, and then call :c:func:`Py_DECREF` for the temporary variable.

7664

7665

7666

-.. cfunction:: void Py_XDECREF(PyObject *o)

7667

+.. c:function:: void Py_XDECREF(PyObject *o)

7668

7669

Decrement the reference count for object *o*. The object may be *NULL*, in

7670

which case the macro has no effect; otherwise the effect is the same as for

7671

- :cfunc:`Py_DECREF`, and the same warning applies.

7672

+ :c:func:`Py_DECREF`, and the same warning applies.

7673

7674

7675

-.. cfunction:: void Py_CLEAR(PyObject *o)

7676

+.. c:function:: void Py_CLEAR(PyObject *o)

7677

7678

Decrement the reference count for object *o*. The object may be *NULL*, in

7679

which case the macro has no effect; otherwise the effect is the same as for

7680

- :cfunc:`Py_DECREF`, except that the argument is also set to *NULL*. The warning

7681

- for :cfunc:`Py_DECREF` does not apply with respect to the object passed because

7682

+ :c:func:`Py_DECREF`, except that the argument is also set to *NULL*. The warning

7683

+ for :c:func:`Py_DECREF` does not apply with respect to the object passed because

7684

the macro carefully uses a temporary variable and sets the argument to *NULL*

7685

before decrementing its reference count.

7686

7687

@@ -65,10 +65,10 @@

7688

7689

The following functions are for runtime dynamic embedding of Python:

7690

``Py_IncRef(PyObject *o)``, ``Py_DecRef(PyObject *o)``. They are

7691

-simply exported function versions of :cfunc:`Py_XINCREF` and

7692

-:cfunc:`Py_XDECREF`, respectively.

7693

+simply exported function versions of :c:func:`Py_XINCREF` and

7694

+:c:func:`Py_XDECREF`, respectively.

7695

7696

The following functions or macros are only for use within the interpreter core:

7697

-:cfunc:`_Py_Dealloc`, :cfunc:`_Py_ForgetReference`, :cfunc:`_Py_NewReference`,

7698

-as well as the global variable :cdata:`_Py_RefTotal`.

7699

+:c:func:`_Py_Dealloc`, :c:func:`_Py_ForgetReference`, :c:func:`_Py_NewReference`,

7700

+as well as the global variable :c:data:`_Py_RefTotal`.

7701

7702

diff -r 8527427914a2 Doc/c-api/reflection.rst

7703

--- a/Doc/c-api/reflection.rst

7704

+++ b/Doc/c-api/reflection.rst

7705

@@ -5,51 +5,51 @@

7706

Reflection

7707

==========

7708

7709

-.. cfunction:: PyObject* PyEval_GetBuiltins()

7710

+.. c:function:: PyObject* PyEval_GetBuiltins()

7711

7712

Return a dictionary of the builtins in the current execution frame,

7713

or the interpreter of the thread state if no frame is currently executing.

7714

7715

7716

-.. cfunction:: PyObject* PyEval_GetLocals()

7717

+.. c:function:: PyObject* PyEval_GetLocals()

7718

7719

Return a dictionary of the local variables in the current execution frame,

7720

or *NULL* if no frame is currently executing.

7721

7722

7723

-.. cfunction:: PyObject* PyEval_GetGlobals()

7724

+.. c:function:: PyObject* PyEval_GetGlobals()

7725

7726

Return a dictionary of the global variables in the current execution frame,

7727

or *NULL* if no frame is currently executing.

7728

7729

7730

-.. cfunction:: PyFrameObject* PyEval_GetFrame()

7731

+.. c:function:: PyFrameObject* PyEval_GetFrame()

7732

7733

Return the current thread state's frame, which is *NULL* if no frame is

7734

currently executing.

7735

7736

7737

-.. cfunction:: int PyFrame_GetLineNumber(PyFrameObject *frame)

7738

+.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)

7739

7740

Return the line number that *frame* is currently executing.

7741

7742

7743

-.. cfunction:: int PyEval_GetRestricted()

7744

+.. c:function:: int PyEval_GetRestricted()

7745

7746

If there is a current frame and it is executing in restricted mode, return true,

7747

otherwise false.

7748

7749

7750

-.. cfunction:: const char* PyEval_GetFuncName(PyObject *func)

7751

+.. c:function:: const char* PyEval_GetFuncName(PyObject *func)

7752

7753

Return the name of *func* if it is a function, class or instance object, else the

7754

name of *func*\s type.

7755

7756

7757

-.. cfunction:: const char* PyEval_GetFuncDesc(PyObject *func)

7758

+.. c:function:: const char* PyEval_GetFuncDesc(PyObject *func)

7759

7760

Return a description string, depending on the type of *func*.

7761

Return values include "()" for functions and methods, " constructor",

7762

" instance", and " object". Concatenated with the result of

7763

- :cfunc:`PyEval_GetFuncName`, the result will be a description of

7764

+ :c:func:`PyEval_GetFuncName`, the result will be a description of

7765

*func*.

7766

diff -r 8527427914a2 Doc/c-api/sequence.rst

7767

--- a/Doc/c-api/sequence.rst

7768

+++ b/Doc/c-api/sequence.rst

7769

@@ -6,13 +6,13 @@

7770

=================

7771

7772

7773

-.. cfunction:: int PySequence_Check(PyObject *o)

7774

+.. c:function:: int PySequence_Check(PyObject *o)

7775

7776

Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.

7777

This function always succeeds.

7778

7779

7780

-.. cfunction:: Py_ssize_t PySequence_Size(PyObject *o)

7781

+.. c:function:: Py_ssize_t PySequence_Size(PyObject *o)

7782

Py_ssize_t PySequence_Length(PyObject *o)

7783

7784

.. index:: builtin: len

7785

@@ -22,140 +22,140 @@

7786

Python expression ``len(o)``.

7787

7788

.. versionchanged:: 2.5

7789

- These functions returned an :ctype:`int` type. This might require

7790

+ These functions returned an :c:type:`int` type. This might require

7791

changes in your code for properly supporting 64-bit systems.

7792

7793

7794

-.. cfunction:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)

7795

+.. c:function:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)

7796

7797

Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.

7798

This is the equivalent of the Python expression ``o1 + o2``.

7799

7800

7801

-.. cfunction:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)

7802

+.. c:function:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)

7803

7804

Return the result of repeating sequence object *o* *count* times, or *NULL* on

7805

failure. This is the equivalent of the Python expression ``o * count``.

7806

7807

.. versionchanged:: 2.5

7808

- This function used an :ctype:`int` type for *count*. This might require

7809

+ This function used an :c:type:`int` type for *count*. This might require

7810

changes in your code for properly supporting 64-bit systems.

7811

7812

7813

-.. cfunction:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)

7814

+.. c:function:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)

7815

7816

Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.

7817

The operation is done *in-place* when *o1* supports it. This is the equivalent

7818

of the Python expression ``o1 += o2``.

7819

7820

7821

-.. cfunction:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)

7822

+.. c:function:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)

7823

7824

Return the result of repeating sequence object *o* *count* times, or *NULL* on

7825

failure. The operation is done *in-place* when *o* supports it. This is the

7826

equivalent of the Python expression ``o *= count``.

7827

7828

.. versionchanged:: 2.5

7829

- This function used an :ctype:`int` type for *count*. This might require

7830

+ This function used an :c:type:`int` type for *count*. This might require

7831

changes in your code for properly supporting 64-bit systems.

7832

7833

7834

-.. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)

7835

+.. c:function:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)

7836

7837

Return the *i*\ th element of *o*, or *NULL* on failure. This is the equivalent of

7838

the Python expression ``o[i]``.

7839

7840

.. versionchanged:: 2.5

7841

- This function used an :ctype:`int` type for *i*. This might require

7842

+ This function used an :c:type:`int` type for *i*. This might require

7843

changes in your code for properly supporting 64-bit systems.

7844

7845

7846

-.. cfunction:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

7847

+.. c:function:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

7848

7849

Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on

7850

failure. This is the equivalent of the Python expression ``o[i1:i2]``.

7851

7852

.. versionchanged:: 2.5

7853

- This function used an :ctype:`int` type for *i1* and *i2*. This might

7854

+ This function used an :c:type:`int` type for *i1* and *i2*. This might

7855

require changes in your code for properly supporting 64-bit systems.

7856

7857

7858

-.. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)

7859

+.. c:function:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)

7860

7861

Assign object *v* to the *i*\ th element of *o*. Returns ``-1`` on failure. This

7862

is the equivalent of the Python statement ``o[i] = v``. This function *does

7863

not* steal a reference to *v*.

7864

7865

.. versionchanged:: 2.5

7866

- This function used an :ctype:`int` type for *i*. This might require

7867

+ This function used an :c:type:`int` type for *i*. This might require

7868

changes in your code for properly supporting 64-bit systems.

7869

7870

7871

-.. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)

7872

+.. c:function:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)

7873

7874

Delete the *i*\ th element of object *o*. Returns ``-1`` on failure. This is the

7875

equivalent of the Python statement ``del o[i]``.

7876

7877

.. versionchanged:: 2.5

7878

- This function used an :ctype:`int` type for *i*. This might require

7879

+ This function used an :c:type:`int` type for *i*. This might require

7880

changes in your code for properly supporting 64-bit systems.

7881

7882

7883

-.. cfunction:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)

7884

+.. c:function:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)

7885

7886

Assign the sequence object *v* to the slice in sequence object *o* from *i1* to

7887

*i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``.

7888

7889

.. versionchanged:: 2.5

7890

- This function used an :ctype:`int` type for *i1* and *i2*. This might

7891

+ This function used an :c:type:`int` type for *i1* and *i2*. This might

7892

require changes in your code for properly supporting 64-bit systems.

7893

7894

7895

-.. cfunction:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

7896

+.. c:function:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

7897

7898

Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` on

7899

failure. This is the equivalent of the Python statement ``del o[i1:i2]``.

7900

7901

.. versionchanged:: 2.5

7902

- This function used an :ctype:`int` type for *i1* and *i2*. This might

7903

+ This function used an :c:type:`int` type for *i1* and *i2*. This might

7904

require changes in your code for properly supporting 64-bit systems.

7905

7906

7907

-.. cfunction:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)

7908

+.. c:function:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)

7909

7910

Return the number of occurrences of *value* in *o*, that is, return the number

7911

of keys for which ``o[key] == value``. On failure, return ``-1``. This is

7912

equivalent to the Python expression ``o.count(value)``.

7913

7914

.. versionchanged:: 2.5

7915

- This function returned an :ctype:`int` type. This might require changes

7916

+ This function returned an :c:type:`int` type. This might require changes

7917

in your code for properly supporting 64-bit systems.

7918

7919

7920

-.. cfunction:: int PySequence_Contains(PyObject *o, PyObject *value)

7921

+.. c:function:: int PySequence_Contains(PyObject *o, PyObject *value)

7922

7923

Determine if *o* contains *value*. If an item in *o* is equal to *value*,

7924

return ``1``, otherwise return ``0``. On error, return ``-1``. This is

7925

equivalent to the Python expression ``value in o``.

7926

7927

7928

-.. cfunction:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)

7929

+.. c:function:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)

7930

7931

Return the first index *i* for which ``o[i] == value``. On error, return

7932

``-1``. This is equivalent to the Python expression ``o.index(value)``.

7933

7934

.. versionchanged:: 2.5

7935

- This function returned an :ctype:`int` type. This might require changes

7936

+ This function returned an :c:type:`int` type. This might require changes

7937

in your code for properly supporting 64-bit systems.

7938

7939

7940

-.. cfunction:: PyObject* PySequence_List(PyObject *o)

7941

+.. c:function:: PyObject* PySequence_List(PyObject *o)

7942

7943

Return a list object with the same contents as the arbitrary sequence *o*. The

7944

returned list is guaranteed to be new.

7945

7946

7947

-.. cfunction:: PyObject* PySequence_Tuple(PyObject *o)

7948

+.. c:function:: PyObject* PySequence_Tuple(PyObject *o)

7949

7950

.. index:: builtin: tuple

7951

7952

@@ -165,28 +165,28 @@

7953

equivalent to the Python expression ``tuple(o)``.

7954

7955

7956

-.. cfunction:: PyObject* PySequence_Fast(PyObject *o, const char *m)

7957

+.. c:function:: PyObject* PySequence_Fast(PyObject *o, const char *m)

7958

7959

Returns the sequence *o* as a tuple, unless it is already a tuple or list, in

7960

- which case *o* is returned. Use :cfunc:`PySequence_Fast_GET_ITEM` to access the

7961

+ which case *o* is returned. Use :c:func:`PySequence_Fast_GET_ITEM` to access the

7962

members of the result. Returns *NULL* on failure. If the object is not a

7963

sequence, raises :exc:`TypeError` with *m* as the message text.

7964

7965

7966

-.. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)

7967

+.. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)

7968

7969

Return the *i*\ th element of *o*, assuming that *o* was returned by

7970

- :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.

7971

+ :c:func:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.

7972

7973

.. versionchanged:: 2.5

7974

- This function used an :ctype:`int` type for *i*. This might require

7975

+ This function used an :c:type:`int` type for *i*. This might require

7976

changes in your code for properly supporting 64-bit systems.

7977

7978

7979

-.. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o)

7980

+.. c:function:: PyObject** PySequence_Fast_ITEMS(PyObject *o)

7981

7982

Return the underlying array of PyObject pointers. Assumes that *o* was returned

7983

- by :cfunc:`PySequence_Fast` and *o* is not *NULL*.

7984

+ by :c:func:`PySequence_Fast` and *o* is not *NULL*.

7985

7986

Note, if a list gets resized, the reallocation may relocate the items array.

7987

So, only use the underlying array pointer in contexts where the sequence

7988

@@ -195,24 +195,24 @@

7989

.. versionadded:: 2.4

7990

7991

7992

-.. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)

7993

+.. c:function:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)

7994

7995

Return the *i*\ th element of *o* or *NULL* on failure. Macro form of

7996

- :cfunc:`PySequence_GetItem` but without checking that

7997

- :cfunc:`PySequence_Check(o)` is true and without adjustment for negative

7998

+ :c:func:`PySequence_GetItem` but without checking that

7999

+ :c:func:`PySequence_Check` on *o* is true and without adjustment for negative

8000

indices.

8001

8002

.. versionadded:: 2.3

8003

8004

.. versionchanged:: 2.5

8005

- This function used an :ctype:`int` type for *i*. This might require

8006

+ This function used an :c:type:`int` type for *i*. This might require

8007

changes in your code for properly supporting 64-bit systems.

8008

8009

8010

-.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)

8011

+.. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)

8012

8013

Returns the length of *o*, assuming that *o* was returned by

8014

- :cfunc:`PySequence_Fast` and that *o* is not *NULL*. The size can also be

8015

- gotten by calling :cfunc:`PySequence_Size` on *o*, but

8016

- :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list

8017

+ :c:func:`PySequence_Fast` and that *o* is not *NULL*. The size can also be

8018

+ gotten by calling :c:func:`PySequence_Size` on *o*, but

8019

+ :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list

8020

or tuple.

8021

diff -r 8527427914a2 Doc/c-api/set.rst

8022

--- a/Doc/c-api/set.rst

8023

+++ b/Doc/c-api/set.rst

8024

@@ -16,20 +16,20 @@

8025

8026

This section details the public API for :class:`set` and :class:`frozenset`

8027

objects. Any functionality not listed below is best accessed using the either

8028

-the abstract object protocol (including :cfunc:`PyObject_CallMethod`,

8029

-:cfunc:`PyObject_RichCompareBool`, :cfunc:`PyObject_Hash`,

8030

-:cfunc:`PyObject_Repr`, :cfunc:`PyObject_IsTrue`, :cfunc:`PyObject_Print`, and

8031

-:cfunc:`PyObject_GetIter`) or the abstract number protocol (including

8032

-:cfunc:`PyNumber_And`, :cfunc:`PyNumber_Subtract`, :cfunc:`PyNumber_Or`,

8033

-:cfunc:`PyNumber_Xor`, :cfunc:`PyNumber_InPlaceAnd`,

8034

-:cfunc:`PyNumber_InPlaceSubtract`, :cfunc:`PyNumber_InPlaceOr`, and

8035

-:cfunc:`PyNumber_InPlaceXor`).

8036

+the abstract object protocol (including :c:func:`PyObject_CallMethod`,

8037

+:c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`,

8038

+:c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and

8039

+:c:func:`PyObject_GetIter`) or the abstract number protocol (including

8040

+:c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`,

8041

+:c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`,

8042

+:c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and

8043

+:c:func:`PyNumber_InPlaceXor`).

8044

8045

8046

-.. ctype:: PySetObject

8047

+.. c:type:: PySetObject

8048

8049

- This subtype of :ctype:`PyObject` is used to hold the internal data for both

8050

- :class:`set` and :class:`frozenset` objects. It is like a :ctype:`PyDictObject`

8051

+ This subtype of :c:type:`PyObject` is used to hold the internal data for both

8052

+ :class:`set` and :class:`frozenset` objects. It is like a :c:type:`PyDictObject`

8053

in that it is a fixed size for small sets (much like tuple storage) and will

8054

point to a separate, variable sized block of memory for medium and large sized

8055

sets (much like list storage). None of the fields of this structure should be

8056

@@ -37,53 +37,53 @@

8057

the documented API rather than by manipulating the values in the structure.

8058

8059

8060

-.. cvar:: PyTypeObject PySet_Type

8061

+.. c:var:: PyTypeObject PySet_Type

8062

8063

- This is an instance of :ctype:`PyTypeObject` representing the Python

8064

+ This is an instance of :c:type:`PyTypeObject` representing the Python

8065

:class:`set` type.

8066

8067

8068

-.. cvar:: PyTypeObject PyFrozenSet_Type

8069

+.. c:var:: PyTypeObject PyFrozenSet_Type

8070

8071

- This is an instance of :ctype:`PyTypeObject` representing the Python

8072

+ This is an instance of :c:type:`PyTypeObject` representing the Python

8073

:class:`frozenset` type.

8074

8075

The following type check macros work on pointers to any Python object. Likewise,

8076

the constructor functions work with any iterable Python object.

8077

8078

8079

-.. cfunction:: int PySet_Check(PyObject *p)

8080

+.. c:function:: int PySet_Check(PyObject *p)

8081

8082

Return true if *p* is a :class:`set` object or an instance of a subtype.

8083

8084

.. versionadded:: 2.6

8085

8086

-.. cfunction:: int PyFrozenSet_Check(PyObject *p)

8087

+.. c:function:: int PyFrozenSet_Check(PyObject *p)

8088

8089

Return true if *p* is a :class:`frozenset` object or an instance of a

8090

subtype.

8091

8092

.. versionadded:: 2.6

8093

8094

-.. cfunction:: int PyAnySet_Check(PyObject *p)

8095

+.. c:function:: int PyAnySet_Check(PyObject *p)

8096

8097

Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an

8098

instance of a subtype.

8099

8100

8101

-.. cfunction:: int PyAnySet_CheckExact(PyObject *p)

8102

+.. c:function:: int PyAnySet_CheckExact(PyObject *p)

8103

8104

Return true if *p* is a :class:`set` object or a :class:`frozenset` object but

8105

not an instance of a subtype.

8106

8107

8108

-.. cfunction:: int PyFrozenSet_CheckExact(PyObject *p)

8109

+.. c:function:: int PyFrozenSet_CheckExact(PyObject *p)

8110

8111

Return true if *p* is a :class:`frozenset` object but not an instance of a

8112

subtype.

8113

8114

8115

-.. cfunction:: PyObject* PySet_New(PyObject *iterable)

8116

+.. c:function:: PyObject* PySet_New(PyObject *iterable)

8117

8118

Return a new :class:`set` containing objects returned by the *iterable*. The

8119

*iterable* may be *NULL* to create a new empty set. Return the new set on

8120

@@ -92,7 +92,7 @@

8121

(``c=set(s)``).

8122

8123

8124

-.. cfunction:: PyObject* PyFrozenSet_New(PyObject *iterable)

8125

+.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)

8126

8127

Return a new :class:`frozenset` containing objects returned by the *iterable*.

8128

The *iterable* may be *NULL* to create a new empty frozenset. Return the new

8129

@@ -108,7 +108,7 @@

8130

or :class:`frozenset` or instances of their subtypes.

8131

8132

8133

-.. cfunction:: Py_ssize_t PySet_Size(PyObject *anyset)

8134

+.. c:function:: Py_ssize_t PySet_Size(PyObject *anyset)

8135

8136

.. index:: builtin: len

8137

8138

@@ -117,16 +117,16 @@

8139

:class:`set`, :class:`frozenset`, or an instance of a subtype.

8140

8141

.. versionchanged:: 2.5

8142

- This function returned an :ctype:`int`. This might require changes in

8143

+ This function returned an :c:type:`int`. This might require changes in

8144

your code for properly supporting 64-bit systems.

8145

8146

8147

-.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)

8148

+.. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)

8149

8150

- Macro form of :cfunc:`PySet_Size` without error checking.

8151

+ Macro form of :c:func:`PySet_Size` without error checking.

8152

8153

8154

-.. cfunction:: int PySet_Contains(PyObject *anyset, PyObject *key)

8155

+.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)

8156

8157

Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike

8158

the Python :meth:`__contains__` method, this function does not automatically

8159

@@ -135,7 +135,7 @@

8160

:class:`set`, :class:`frozenset`, or an instance of a subtype.

8161

8162

8163

-.. cfunction:: int PySet_Add(PyObject *set, PyObject *key)

8164

+.. c:function:: int PySet_Add(PyObject *set, PyObject *key)

8165

8166

Add *key* to a :class:`set` instance. Does not apply to :class:`frozenset`

8167

instances. Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if

8168

@@ -145,14 +145,14 @@

8169

8170

.. versionchanged:: 2.6

8171

Now works with instances of :class:`frozenset` or its subtypes.

8172

- Like :cfunc:`PyTuple_SetItem` in that it can be used to fill-in the

8173

+ Like :c:func:`PyTuple_SetItem` in that it can be used to fill-in the

8174

values of brand new frozensets before they are exposed to other code.

8175

8176

The following functions are available for instances of :class:`set` or its

8177

subtypes but not for instances of :class:`frozenset` or its subtypes.

8178

8179

8180

-.. cfunction:: int PySet_Discard(PyObject *set, PyObject *key)

8181

+.. c:function:: int PySet_Discard(PyObject *set, PyObject *key)

8182

8183

Return 1 if found and removed, 0 if not found (no action taken), and -1 if an

8184

error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a

8185

@@ -162,7 +162,7 @@

8186

instance of :class:`set` or its subtype.

8187

8188

8189

-.. cfunction:: PyObject* PySet_Pop(PyObject *set)

8190

+.. c:function:: PyObject* PySet_Pop(PyObject *set)

8191

8192

Return a new reference to an arbitrary object in the *set*, and removes the

8193

object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the

8194

@@ -170,6 +170,6 @@

8195

:class:`set` or its subtype.

8196

8197

8198

-.. cfunction:: int PySet_Clear(PyObject *set)

8199

+.. c:function:: int PySet_Clear(PyObject *set)

8200

8201

Empty an existing set of all elements.

8202

diff -r 8527427914a2 Doc/c-api/slice.rst

8203

--- a/Doc/c-api/slice.rst

8204

+++ b/Doc/c-api/slice.rst

8205

@@ -6,7 +6,7 @@

8206

-------------

8207

8208

8209

-.. cvar:: PyTypeObject PySlice_Type

8210

+.. c:var:: PyTypeObject PySlice_Type

8211

8212

.. index:: single: SliceType (in module types)

8213

8214

@@ -14,12 +14,12 @@

8215

``types.SliceType``.

8216

8217

8218

-.. cfunction:: int PySlice_Check(PyObject *ob)

8219

+.. c:function:: int PySlice_Check(PyObject *ob)

8220

8221

Return true if *ob* is a slice object; *ob* must not be *NULL*.

8222

8223

8224

-.. cfunction:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)

8225

+.. c:function:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)

8226

8227

Return a new slice object with the given values. The *start*, *stop*, and

8228

*step* parameters are used as the values of the slice object attributes of

8229

@@ -28,7 +28,7 @@

8230

the new object could not be allocated.

8231

8232

8233

-.. cfunction:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)

8234

+.. c:function:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)

8235

8236

Retrieve the start, stop and step indices from the slice object *slice*,

8237

assuming a sequence of length *length*. Treats indices greater than

8238

@@ -40,18 +40,18 @@

8239

8240

You probably do not want to use this function. If you want to use slice

8241

objects in versions of Python prior to 2.3, you would probably do well to

8242

- incorporate the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed,

8243

+ incorporate the source of :c:func:`PySlice_GetIndicesEx`, suitably renamed,

8244

in the source of your extension.

8245

8246

.. versionchanged:: 2.5

8247

- This function used an :ctype:`int` type for *length* and an

8248

- :ctype:`int *` type for *start*, *stop*, and *step*. This might require

8249

+ This function used an :c:type:`int` type for *length* and an

8250

+ :c:type:`int *` type for *start*, *stop*, and *step*. This might require

8251

changes in your code for properly supporting 64-bit systems.

8252

8253

8254

-.. cfunction:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)

8255

+.. c:function:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)

8256

8257

- Usable replacement for :cfunc:`PySlice_GetIndices`. Retrieve the start,

8258

+ Usable replacement for :c:func:`PySlice_GetIndices`. Retrieve the start,

8259

stop, and step indices from the slice object *slice* assuming a sequence of

8260

length *length*, and store the length of the slice in *slicelength*. Out

8261

of bounds indices are clipped in a manner consistent with the handling of

8262

@@ -62,7 +62,7 @@

8263

.. versionadded:: 2.3

8264

8265

.. versionchanged:: 2.5

8266

- This function used an :ctype:`int` type for *length* and an

8267

- :ctype:`int *` type for *start*, *stop*, *step*, and *slicelength*. This

8268

+ This function used an :c:type:`int` type for *length* and an

8269

+ :c:type:`int *` type for *start*, *stop*, *step*, and *slicelength*. This

8270

might require changes in your code for properly supporting 64-bit

8271

systems.

8272

diff -r 8527427914a2 Doc/c-api/string.rst

8273

--- a/Doc/c-api/string.rst

8274

+++ b/Doc/c-api/string.rst

8275

@@ -17,20 +17,20 @@

8276

.. index:: object: string

8277

8278

8279

-.. ctype:: PyStringObject

8280

+.. c:type:: PyStringObject

8281

8282

- This subtype of :ctype:`PyObject` represents a Python string object.

8283

+ This subtype of :c:type:`PyObject` represents a Python string object.

8284

8285

8286

-.. cvar:: PyTypeObject PyString_Type

8287

+.. c:var:: PyTypeObject PyString_Type

8288

8289

.. index:: single: StringType (in module types)

8290

8291

- This instance of :ctype:`PyTypeObject` represents the Python string type; it is

8292

+ This instance of :c:type:`PyTypeObject` represents the Python string type; it is

8293

the same object as ``str`` and ``types.StringType`` in the Python layer. .

8294

8295

8296

-.. cfunction:: int PyString_Check(PyObject *o)

8297

+.. c:function:: int PyString_Check(PyObject *o)

8298

8299

Return true if the object *o* is a string object or an instance of a subtype of

8300

the string type.

8301

@@ -39,7 +39,7 @@

8302

Allowed subtypes to be accepted.

8303

8304

8305

-.. cfunction:: int PyString_CheckExact(PyObject *o)

8306

+.. c:function:: int PyString_CheckExact(PyObject *o)

8307

8308

Return true if the object *o* is a string object, but not an instance of a

8309

subtype of the string type.

8310

@@ -47,27 +47,27 @@

8311

.. versionadded:: 2.2

8312

8313

8314

-.. cfunction:: PyObject* PyString_FromString(const char *v)

8315

+.. c:function:: PyObject* PyString_FromString(const char *v)

8316

8317

Return a new string object with a copy of the string *v* as value on success,

8318

and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be

8319

checked.

8320

8321

8322

-.. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)

8323

+.. c:function:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)

8324

8325

Return a new string object with a copy of the string *v* as value and length

8326

*len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of the

8327

string are uninitialized.

8328

8329

.. versionchanged:: 2.5

8330

- This function used an :ctype:`int` type for *len*. This might require

8331

+ This function used an :c:type:`int` type for *len*. This might require

8332

changes in your code for properly supporting 64-bit systems.

8333

8334

8335

-.. cfunction:: PyObject* PyString_FromFormat(const char *format, ...)

8336

+.. c:function:: PyObject* PyString_FromFormat(const char *format, ...)

8337

8338

- Take a C :cfunc:`printf`\ -style *format* string and a variable number of

8339

+ Take a C :c:func:`printf`\ -style *format* string and a variable number of

8340

arguments, calculate the size of the resulting Python string and return a string

8341

with the values formatted into it. The variable arguments must be C types and

8342

must correspond exactly to the format characters in the *format* string. The

8343

@@ -144,31 +144,31 @@

8344

Support for `"%lld"` and `"%llu"` added.

8345

8346

8347

-.. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)

8348

+.. c:function:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)

8349

8350

- Identical to :cfunc:`PyString_FromFormat` except that it takes exactly two

8351

+ Identical to :c:func:`PyString_FromFormat` except that it takes exactly two

8352

arguments.

8353

8354

8355

-.. cfunction:: Py_ssize_t PyString_Size(PyObject *string)

8356

+.. c:function:: Py_ssize_t PyString_Size(PyObject *string)

8357

8358

Return the length of the string in string object *string*.

8359

8360

.. versionchanged:: 2.5

8361

- This function returned an :ctype:`int` type. This might require changes

8362

+ This function returned an :c:type:`int` type. This might require changes

8363

in your code for properly supporting 64-bit systems.

8364

8365

8366

-.. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string)

8367

+.. c:function:: Py_ssize_t PyString_GET_SIZE(PyObject *string)

8368

8369

- Macro form of :cfunc:`PyString_Size` but without error checking.

8370

+ Macro form of :c:func:`PyString_Size` but without error checking.

8371

8372

.. versionchanged:: 2.5

8373

- This macro returned an :ctype:`int` type. This might require changes in

8374

+ This macro returned an :c:type:`int` type. This might require changes in

8375

your code for properly supporting 64-bit systems.

8376

8377

8378

-.. cfunction:: char* PyString_AsString(PyObject *string)

8379

+.. c:function:: char* PyString_AsString(PyObject *string)

8380

8381

Return a NUL-terminated representation of the contents of *string*. The pointer

8382

refers to the internal buffer of *string*, not a copy. The data must not be

8383

@@ -176,16 +176,16 @@

8384

``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If

8385

*string* is a Unicode object, this function computes the default encoding of

8386

*string* and operates on that. If *string* is not a string object at all,

8387

- :cfunc:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.

8388

+ :c:func:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.

8389

8390

8391

-.. cfunction:: char* PyString_AS_STRING(PyObject *string)

8392

+.. c:function:: char* PyString_AS_STRING(PyObject *string)

8393

8394

- Macro form of :cfunc:`PyString_AsString` but without error checking. Only

8395

+ Macro form of :c:func:`PyString_AsString` but without error checking. Only

8396

string objects are supported; no Unicode objects should be passed.

8397

8398

8399

-.. cfunction:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)

8400

+.. c:function:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)

8401

8402

Return a NUL-terminated representation of the contents of the object *obj*

8403

through the output variables *buffer* and *length*.

8404

@@ -200,14 +200,14 @@

8405

``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If

8406

*string* is a Unicode object, this function computes the default encoding of

8407

*string* and operates on that. If *string* is not a string object at all,

8408

- :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.

8409

+ :c:func:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.

8410

8411

.. versionchanged:: 2.5

8412

- This function used an :ctype:`int *` type for *length*. This might

8413

+ This function used an :c:type:`int *` type for *length*. This might

8414

require changes in your code for properly supporting 64-bit systems.

8415

8416

8417

-.. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart)

8418

+.. c:function:: void PyString_Concat(PyObject **string, PyObject *newpart)

8419

8420

Create a new string object in *\*string* containing the contents of *newpart*

8421

appended to *string*; the caller will own the new reference. The reference to

8422

@@ -216,13 +216,13 @@

8423

*\*string* will be set to *NULL*; the appropriate exception will be set.

8424

8425

8426

-.. cfunction:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)

8427

+.. c:function:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)

8428

8429

Create a new string object in *\*string* containing the contents of *newpart*

8430

appended to *string*. This version decrements the reference count of *newpart*.

8431

8432

8433

-.. cfunction:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize)

8434

+.. c:function:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize)

8435

8436

A way to resize a string object even though it is "immutable". Only use this to

8437

build up a brand new string object; don't use this if the string may already be

8438

@@ -235,16 +235,16 @@

8439

set to *NULL*, a memory exception is set, and ``-1`` is returned.

8440

8441

.. versionchanged:: 2.5

8442

- This function used an :ctype:`int` type for *newsize*. This might

8443

+ This function used an :c:type:`int` type for *newsize*. This might

8444

require changes in your code for properly supporting 64-bit systems.

8445

8446

-.. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args)

8447

+.. c:function:: PyObject* PyString_Format(PyObject *format, PyObject *args)

8448

8449

Return a new string object from *format* and *args*. Analogous to ``format %

8450

args``. The *args* argument must be a tuple.

8451

8452

8453

-.. cfunction:: void PyString_InternInPlace(PyObject **string)

8454

+.. c:function:: void PyString_InternInPlace(PyObject **string)

8455

8456

Intern the argument *\*string* in place. The argument must be the address of a

8457

pointer variable pointing to a Python string object. If there is an existing

8458

@@ -261,10 +261,10 @@

8459

This function is not available in 3.x and does not have a PyBytes alias.

8460

8461

8462

-.. cfunction:: PyObject* PyString_InternFromString(const char *v)

8463

+.. c:function:: PyObject* PyString_InternFromString(const char *v)

8464

8465

- A combination of :cfunc:`PyString_FromString` and

8466

- :cfunc:`PyString_InternInPlace`, returning either a new string object that has

8467

+ A combination of :c:func:`PyString_FromString` and

8468

+ :c:func:`PyString_InternInPlace`, returning either a new string object that has

8469

been interned, or a new ("owned") reference to an earlier interned string object

8470

with the same value.

8471

8472

@@ -273,7 +273,7 @@

8473

This function is not available in 3.x and does not have a PyBytes alias.

8474

8475

8476

-.. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)

8477

+.. c:function:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)

8478

8479

Create an object by decoding *size* bytes of the encoded buffer *s* using the

8480

codec registered for *encoding*. *encoding* and *errors* have the same meaning

8481

@@ -286,11 +286,11 @@

8482

This function is not available in 3.x and does not have a PyBytes alias.

8483

8484

.. versionchanged:: 2.5

8485

- This function used an :ctype:`int` type for *size*. This might require

8486

+ This function used an :c:type:`int` type for *size*. This might require

8487

changes in your code for properly supporting 64-bit systems.

8488

8489

8490

-.. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)

8491

+.. c:function:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)

8492

8493

Decode a string object by passing it to the codec registered for *encoding* and

8494

return the result as Python object. *encoding* and *errors* have the same

8495

@@ -303,9 +303,9 @@

8496

This function is not available in 3.x and does not have a PyBytes alias.

8497

8498

8499

-.. cfunction:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)

8500

+.. c:function:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)

8501

8502

- Encode the :ctype:`char` buffer of the given size by passing it to the codec

8503

+ Encode the :c:type:`char` buffer of the given size by passing it to the codec

8504

registered for *encoding* and return a Python object. *encoding* and *errors*

8505

have the same meaning as the parameters of the same name in the string

8506

:meth:`encode` method. The codec to be used is looked up using the Python codec

8507

@@ -316,11 +316,11 @@

8508

This function is not available in 3.x and does not have a PyBytes alias.

8509

8510

.. versionchanged:: 2.5

8511

- This function used an :ctype:`int` type for *size*. This might require

8512

+ This function used an :c:type:`int` type for *size*. This might require

8513

changes in your code for properly supporting 64-bit systems.

8514

8515

8516

-.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)

8517

+.. c:function:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)

8518

8519

Encode a string object using the codec registered for *encoding* and return the

8520

result as Python object. *encoding* and *errors* have the same meaning as the

8521

diff -r 8527427914a2 Doc/c-api/structures.rst

8522

--- a/Doc/c-api/structures.rst

8523

+++ b/Doc/c-api/structures.rst

8524

@@ -11,12 +11,12 @@

8525

8526

All Python objects ultimately share a small number of fields at the beginning

8527

of the object's representation in memory. These are represented by the

8528

-:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn,

8529

+:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn,

8530

by the expansions of some macros also used, whether directly or indirectly, in

8531

the definition of all other Python objects.

8532

8533

8534

-.. ctype:: PyObject

8535

+.. c:type:: PyObject

8536

8537

All object types are extensions of this type. This is a type which

8538

contains the information Python needs to treat a pointer to an object as an

8539

@@ -26,79 +26,79 @@

8540

macro.

8541

8542

8543

-.. ctype:: PyVarObject

8544

+.. c:type:: PyVarObject

8545

8546

- This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size`

8547

+ This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`

8548

field. This is only used for objects that have some notion of *length*.

8549

This type does not often appear in the Python/C API. It corresponds to the

8550

fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro.

8551

8552

-These macros are used in the definition of :ctype:`PyObject` and

8553

-:ctype:`PyVarObject`:

8554

+These macros are used in the definition of :c:type:`PyObject` and

8555

+:c:type:`PyVarObject`:

8556

8557

8558

-.. cmacro:: PyObject_HEAD

8559

+.. c:macro:: PyObject_HEAD

8560

8561

This is a macro which expands to the declarations of the fields of the

8562

- :ctype:`PyObject` type; it is used when declaring new types which represent

8563

+ :c:type:`PyObject` type; it is used when declaring new types which represent

8564

objects without a varying length. The specific fields it expands to depend

8565

- on the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is

8566

- not defined, and :cmacro:`PyObject_HEAD` expands to::

8567

+ on the definition of :c:macro:`Py_TRACE_REFS`. By default, that macro is

8568

+ not defined, and :c:macro:`PyObject_HEAD` expands to::

8569

8570

Py_ssize_t ob_refcnt;

8571

PyTypeObject *ob_type;

8572

8573

- When :cmacro:`Py_TRACE_REFS` is defined, it expands to::

8574

+ When :c:macro:`Py_TRACE_REFS` is defined, it expands to::

8575

8576

PyObject *_ob_next, *_ob_prev;

8577

Py_ssize_t ob_refcnt;

8578

PyTypeObject *ob_type;

8579

8580

8581

-.. cmacro:: PyObject_VAR_HEAD

8582

+.. c:macro:: PyObject_VAR_HEAD

8583

8584

This is a macro which expands to the declarations of the fields of the

8585

- :ctype:`PyVarObject` type; it is used when declaring new types which

8586

+ :c:type:`PyVarObject` type; it is used when declaring new types which

8587

represent objects with a length that varies from instance to instance.

8588

This macro always expands to::

8589

8590

PyObject_HEAD

8591

Py_ssize_t ob_size;

8592

8593

- Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own

8594

- expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`.

8595

+ Note that :c:macro:`PyObject_HEAD` is part of the expansion, and that its own

8596

+ expansion varies depending on the definition of :c:macro:`Py_TRACE_REFS`.

8597

8598

8599

-.. cmacro:: PyObject_HEAD_INIT(type)

8600

+.. c:macro:: PyObject_HEAD_INIT(type)

8601

8602

This is a macro which expands to initialization values for a new

8603

- :ctype:`PyObject` type. This macro expands to::

8604

+ :c:type:`PyObject` type. This macro expands to::

8605

8606

_PyObject_EXTRA_INIT

8607

1, type,

8608

8609

8610

-.. cmacro:: PyVarObject_HEAD_INIT(type, size)

8611

+.. c:macro:: PyVarObject_HEAD_INIT(type, size)

8612

8613

This is a macro which expands to initialization values for a new

8614

- :ctype:`PyVarObject` type, including the :attr:`ob_size` field.

8615

+ :c:type:`PyVarObject` type, including the :attr:`ob_size` field.

8616

This macro expands to::

8617

8618

_PyObject_EXTRA_INIT

8619

1, type, size,

8620

8621

8622

-.. ctype:: PyCFunction

8623

+.. c:type:: PyCFunction

8624

8625

Type of the functions used to implement most Python callables in C.

8626

- Functions of this type take two :ctype:`PyObject\*` parameters and return

8627

+ Functions of this type take two :c:type:`PyObject\*` parameters and return

8628

one such value. If the return value is *NULL*, an exception shall have

8629

been set. If not *NULL*, the return value is interpreted as the return

8630

value of the function as exposed in Python. The function must return a new

8631

reference.

8632

8633

8634

-.. ctype:: PyMethodDef

8635

+.. c:type:: PyMethodDef

8636

8637

Structure used to describe a method of an extension type. This structure has

8638

four fields:

8639

@@ -119,10 +119,10 @@

8640

+------------------+-------------+-------------------------------+

8641

8642

The :attr:`ml_meth` is a C function pointer. The functions may be of different

8643

-types, but they always return :ctype:`PyObject\*`. If the function is not of

8644

-the :ctype:`PyCFunction`, the compiler will require a cast in the method table.

8645

-Even though :ctype:`PyCFunction` defines the first parameter as

8646

-:ctype:`PyObject\*`, it is common that the method implementation uses a the

8647

+types, but they always return :c:type:`PyObject\*`. If the function is not of

8648

+the :c:type:`PyCFunction`, the compiler will require a cast in the method table.

8649

+Even though :c:type:`PyCFunction` defines the first parameter as

8650

+:c:type:`PyObject\*`, it is common that the method implementation uses a the

8651

specific C type of the *self* object.

8652

8653

The :attr:`ml_flags` field is a bitfield which can include the following flags.

8654

@@ -136,27 +136,27 @@

8655

.. data:: METH_VARARGS

8656

8657

This is the typical calling convention, where the methods have the type

8658

- :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values.

8659

+ :c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.

8660

The first one is the *self* object for methods; for module functions, it is

8661

the module object. The second parameter (often called *args*) is a tuple

8662

object representing all arguments. This parameter is typically processed

8663

- using :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`.

8664

+ using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.

8665

8666

8667

.. data:: METH_KEYWORDS

8668

8669

- Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`.

8670

+ Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.

8671

The function expects three parameters: *self*, *args*, and a dictionary of

8672

all the keyword arguments. The flag is typically combined with

8673

:const:`METH_VARARGS`, and the parameters are typically processed using

8674

- :cfunc:`PyArg_ParseTupleAndKeywords`.

8675

+ :c:func:`PyArg_ParseTupleAndKeywords`.

8676

8677

8678

.. data:: METH_NOARGS

8679

8680

Methods without parameters don't need to check whether arguments are given if

8681

they are listed with the :const:`METH_NOARGS` flag. They need to be of type

8682

- :ctype:`PyCFunction`. The first parameter is typically named ``self`` and

8683

+ :c:type:`PyCFunction`. The first parameter is typically named ``self`` and

8684

will hold a reference to the module or object instance. In all cases the

8685

second parameter will be *NULL*.

8686

8687

@@ -164,15 +164,15 @@

8688

.. data:: METH_O

8689

8690

Methods with a single object argument can be listed with the :const:`METH_O`

8691

- flag, instead of invoking :cfunc:`PyArg_ParseTuple` with a ``"O"`` argument.

8692

- They have the type :ctype:`PyCFunction`, with the *self* parameter, and a

8693

- :ctype:`PyObject\*` parameter representing the single argument.

8694

+ flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.

8695

+ They have the type :c:type:`PyCFunction`, with the *self* parameter, and a

8696

+ :c:type:`PyObject\*` parameter representing the single argument.

8697

8698

8699

.. data:: METH_OLDARGS

8700

8701

This calling convention is deprecated. The method must be of type

8702

- :ctype:`PyCFunction`. The second argument is *NULL* if no arguments are

8703

+ :c:type:`PyCFunction`. The second argument is *NULL* if no arguments are

8704

given, a single object if exactly one argument is given, and a tuple of

8705

objects if more than one argument is given. There is no way for a function

8706

using this convention to distinguish between a call with multiple arguments

8707

@@ -225,7 +225,7 @@

8708

.. versionadded:: 2.4

8709

8710

8711

-.. ctype:: PyMemberDef

8712

+.. c:type:: PyMemberDef

8713

8714

Structure which describes an attribute of a type which corresponds to a C

8715

struct member. Its fields are:

8716

@@ -277,22 +277,22 @@

8717

T_PYSSIZET Py_ssize_t

8718

=============== ==================

8719

8720

- :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX` differ in that

8721

- :cmacro:`T_OBJECT` returns ``None`` if the member is *NULL* and

8722

- :cmacro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use

8723

- :cmacro:`T_OBJECT_EX` over :cmacro:`T_OBJECT` because :cmacro:`T_OBJECT_EX`

8724

+ :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that

8725

+ :c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and

8726

+ :c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use

8727

+ :c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX`

8728

handles use of the :keyword:`del` statement on that attribute more correctly

8729

- than :cmacro:`T_OBJECT`.

8730

+ than :c:macro:`T_OBJECT`.

8731

8732

- :attr:`flags` can be 0 for write and read access or :cmacro:`READONLY` for

8733

- read-only access. Using :cmacro:`T_STRING` for :attr:`type` implies

8734

- :cmacro:`READONLY`. Only :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX`

8735

+ :attr:`flags` can be 0 for write and read access or :c:macro:`READONLY` for

8736

+ read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies

8737

+ :c:macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`

8738

members can be deleted. (They are set to *NULL*).

8739

8740

8741

-.. cfunction:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)

8742

+.. c:function:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)

8743

8744

Return a bound method object for an extension type implemented in C. This

8745

can be useful in the implementation of a :attr:`tp_getattro` or

8746

:attr:`tp_getattr` handler that does not use the

8747

- :cfunc:`PyObject_GenericGetAttr` function.

8748

+ :c:func:`PyObject_GenericGetAttr` function.

8749

diff -r 8527427914a2 Doc/c-api/sys.rst

8750

--- a/Doc/c-api/sys.rst

8751

+++ b/Doc/c-api/sys.rst

8752

@@ -6,16 +6,16 @@

8753

==========================

8754

8755

8756

-.. cfunction:: int Py_FdIsInteractive(FILE *fp, const char *filename)

8757

+.. c:function:: int Py_FdIsInteractive(FILE *fp, const char *filename)

8758

8759

Return true (nonzero) if the standard I/O file *fp* with name *filename* is

8760

deemed interactive. This is the case for files for which ``isatty(fileno(fp))``

8761

- is true. If the global flag :cdata:`Py_InteractiveFlag` is true, this function

8762

+ is true. If the global flag :c:data:`Py_InteractiveFlag` is true, this function

8763

also returns true if the *filename* pointer is *NULL* or if the name is equal to

8764

one of the strings ``'<stdin>'`` or ``'???'``.

8765

8766

8767

-.. cfunction:: void PyOS_AfterFork()

8768

+.. c:function:: void PyOS_AfterFork()

8769

8770

Function to update some internal state after a process fork; this should be

8771

called in the new process if the Python interpreter will continue to be used.

8772

@@ -23,7 +23,7 @@

8773

to be called.

8774

8775

8776

-.. cfunction:: int PyOS_CheckStack()

8777

+.. c:function:: int PyOS_CheckStack()

8778

8779

Return true when the interpreter runs out of stack space. This is a reliable

8780

check, but is only available when :const:`USE_STACKCHECK` is defined (currently

8781

@@ -32,20 +32,20 @@

8782

own code.

8783

8784

8785

-.. cfunction:: PyOS_sighandler_t PyOS_getsig(int i)

8786

+.. c:function:: PyOS_sighandler_t PyOS_getsig(int i)

8787

8788

Return the current signal handler for signal *i*. This is a thin wrapper around

8789

- either :cfunc:`sigaction` or :cfunc:`signal`. Do not call those functions

8790

- directly! :ctype:`PyOS_sighandler_t` is a typedef alias for :ctype:`void

8791

+ either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions

8792

+ directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void

8793

(\*)(int)`.

8794

8795

8796

-.. cfunction:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

8797

+.. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

8798

8799

Set the signal handler for signal *i* to be *h*; return the old signal handler.

8800

- This is a thin wrapper around either :cfunc:`sigaction` or :cfunc:`signal`. Do

8801

- not call those functions directly! :ctype:`PyOS_sighandler_t` is a typedef

8802

- alias for :ctype:`void (\*)(int)`.

8803

+ This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do

8804

+ not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef

8805

+ alias for :c:type:`void (\*)(int)`.

8806

8807

.. _systemfunctions:

8808

8809

@@ -56,38 +56,38 @@

8810

accessible to C code. They all work with the current interpreter thread's

8811

:mod:`sys` module's dict, which is contained in the internal thread state structure.

8812

8813

-.. cfunction:: PyObject *PySys_GetObject(char *name)

8814

+.. c:function:: PyObject *PySys_GetObject(char *name)

8815

8816

Return the object *name* from the :mod:`sys` module or *NULL* if it does

8817

not exist, without setting an exception.

8818

8819

-.. cfunction:: FILE *PySys_GetFile(char *name, FILE *def)

8820

+.. c:function:: FILE *PySys_GetFile(char *name, FILE *def)

8821

8822

- Return the :ctype:`FILE*` associated with the object *name* in the

8823

+ Return the :c:type:`FILE*` associated with the object *name* in the

8824

:mod:`sys` module, or *def* if *name* is not in the module or is not associated

8825

- with a :ctype:`FILE*`.

8826

+ with a :c:type:`FILE*`.

8827

8828

-.. cfunction:: int PySys_SetObject(char *name, PyObject *v)

8829

+.. c:function:: int PySys_SetObject(char *name, PyObject *v)

8830

8831

Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which

8832

case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``

8833

on error.

8834

8835

-.. cfunction:: void PySys_ResetWarnOptions()

8836

+.. c:function:: void PySys_ResetWarnOptions()

8837

8838

Reset :data:`sys.warnoptions` to an empty list.

8839

8840

-.. cfunction:: void PySys_AddWarnOption(char *s)

8841

+.. c:function:: void PySys_AddWarnOption(char *s)

8842

8843

Append *s* to :data:`sys.warnoptions`.

8844

8845

-.. cfunction:: void PySys_SetPath(char *path)

8846

+.. c:function:: void PySys_SetPath(char *path)

8847

8848

Set :data:`sys.path` to a list object of paths found in *path* which should

8849

be a list of paths separated with the platform's search path delimiter

8850

(``:`` on Unix, ``;`` on Windows).

8851

8852

-.. cfunction:: void PySys_WriteStdout(const char *format, ...)

8853

+.. c:function:: void PySys_WriteStdout(const char *format, ...)

8854

8855

Write the output string described by *format* to :data:`sys.stdout`. No

8856

exceptions are raised, even if truncation occurs (see below).

8857

@@ -103,7 +103,7 @@

8858

If a problem occurs, or :data:`sys.stdout` is unset, the formatted message

8859

is written to the real (C level) *stdout*.

8860

8861

-.. cfunction:: void PySys_WriteStderr(const char *format, ...)

8862

+.. c:function:: void PySys_WriteStderr(const char *format, ...)

8863

8864

As above, but write to :data:`sys.stderr` or *stderr* instead.

8865

8866

@@ -114,7 +114,7 @@

8867

===============

8868

8869

8870

-.. cfunction:: void Py_FatalError(const char *message)

8871

+.. c:function:: void Py_FatalError(const char *message)

8872

8873

.. index:: single: abort()

8874

8875

@@ -122,30 +122,30 @@

8876

This function should only be invoked when a condition is detected that would

8877

make it dangerous to continue using the Python interpreter; e.g., when the

8878

object administration appears to be corrupted. On Unix, the standard C library

8879

- function :cfunc:`abort` is called which will attempt to produce a :file:`core`

8880

+ function :c:func:`abort` is called which will attempt to produce a :file:`core`

8881

file.

8882

8883

8884

-.. cfunction:: void Py_Exit(int status)

8885

+.. c:function:: void Py_Exit(int status)

8886

8887

.. index::

8888

single: Py_Finalize()

8889

single: exit()

8890

8891

- Exit the current process. This calls :cfunc:`Py_Finalize` and then calls the

8892

+ Exit the current process. This calls :c:func:`Py_Finalize` and then calls the

8893

standard C library function ``exit(status)``.

8894

8895

8896

-.. cfunction:: int Py_AtExit(void (*func) ())

8897

+.. c:function:: int Py_AtExit(void (*func) ())

8898

8899

.. index::

8900

single: Py_Finalize()

8901

single: cleanup functions

8902

8903

- Register a cleanup function to be called by :cfunc:`Py_Finalize`. The cleanup

8904

+ Register a cleanup function to be called by :c:func:`Py_Finalize`. The cleanup

8905

function will be called with no arguments and should return no value. At most

8906

32 cleanup functions can be registered. When the registration is successful,

8907

- :cfunc:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup

8908

+ :c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup

8909

function registered last is called first. Each cleanup function will be called

8910

at most once. Since Python's internal finalization will have completed before

8911

the cleanup function, no Python APIs should be called by *func*.

8912

diff -r 8527427914a2 Doc/c-api/tuple.rst

8913

--- a/Doc/c-api/tuple.rst

8914

+++ b/Doc/c-api/tuple.rst

8915

@@ -8,20 +8,20 @@

8916

.. index:: object: tuple

8917

8918

8919

-.. ctype:: PyTupleObject

8920

+.. c:type:: PyTupleObject

8921

8922

- This subtype of :ctype:`PyObject` represents a Python tuple object.

8923

+ This subtype of :c:type:`PyObject` represents a Python tuple object.

8924

8925

8926

-.. cvar:: PyTypeObject PyTuple_Type

8927

+.. c:var:: PyTypeObject PyTuple_Type

8928

8929

.. index:: single: TupleType (in module types)

8930

8931

- This instance of :ctype:`PyTypeObject` represents the Python tuple type; it is

8932

+ This instance of :c:type:`PyTypeObject` represents the Python tuple type; it is

8933

the same object as ``tuple`` and ``types.TupleType`` in the Python layer..

8934

8935

8936

-.. cfunction:: int PyTuple_Check(PyObject *p)

8937

+.. c:function:: int PyTuple_Check(PyObject *p)

8938

8939

Return true if *p* is a tuple object or an instance of a subtype of the tuple

8940

type.

8941

@@ -30,7 +30,7 @@

8942

Allowed subtypes to be accepted.

8943

8944

8945

-.. cfunction:: int PyTuple_CheckExact(PyObject *p)

8946

+.. c:function:: int PyTuple_CheckExact(PyObject *p)

8947

8948

Return true if *p* is a tuple object, but not an instance of a subtype of the

8949

tuple type.

8950

@@ -38,16 +38,16 @@

8951

.. versionadded:: 2.2

8952

8953

8954

-.. cfunction:: PyObject* PyTuple_New(Py_ssize_t len)

8955

+.. c:function:: PyObject* PyTuple_New(Py_ssize_t len)

8956

8957

Return a new tuple object of size *len*, or *NULL* on failure.

8958

8959

.. versionchanged:: 2.5

8960

- This function used an :ctype:`int` type for *len*. This might require

8961

+ This function used an :c:type:`int` type for *len*. This might require

8962

changes in your code for properly supporting 64-bit systems.

8963

8964

8965

-.. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)

8966

+.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)

8967

8968

Return a new tuple object of size *n*, or *NULL* on failure. The tuple values

8969

are initialized to the subsequent *n* C arguments pointing to Python objects.

8970

@@ -56,59 +56,59 @@

8971

.. versionadded:: 2.4

8972

8973

.. versionchanged:: 2.5

8974

- This function used an :ctype:`int` type for *n*. This might require

8975

+ This function used an :c:type:`int` type for *n*. This might require

8976

changes in your code for properly supporting 64-bit systems.

8977

8978

8979

-.. cfunction:: Py_ssize_t PyTuple_Size(PyObject *p)

8980

+.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)

8981

8982

Take a pointer to a tuple object, and return the size of that tuple.

8983

8984

.. versionchanged:: 2.5

8985

- This function returned an :ctype:`int` type. This might require changes

8986

+ This function returned an :c:type:`int` type. This might require changes

8987

in your code for properly supporting 64-bit systems.

8988

8989

8990

-.. cfunction:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

8991

+.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

8992

8993

Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;

8994

no error checking is performed.

8995

8996

.. versionchanged:: 2.5

8997

- This function returned an :ctype:`int` type. This might require changes

8998

+ This function returned an :c:type:`int` type. This might require changes

8999

in your code for properly supporting 64-bit systems.

9000

9001

9002

-.. cfunction:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)

9003

+.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)

9004

9005

Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is

9006

out of bounds, return *NULL* and sets an :exc:`IndexError` exception.

9007

9008

.. versionchanged:: 2.5

9009

- This function used an :ctype:`int` type for *pos*. This might require

9010

+ This function used an :c:type:`int` type for *pos*. This might require

9011

changes in your code for properly supporting 64-bit systems.

9012

9013

9014

-.. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

9015

+.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

9016

9017

- Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments.

9018

+ Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments.

9019

9020

.. versionchanged:: 2.5

9021

- This function used an :ctype:`int` type for *pos*. This might require

9022

+ This function used an :c:type:`int` type for *pos*. This might require

9023

changes in your code for properly supporting 64-bit systems.

9024

9025

9026

-.. cfunction:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)

9027

+.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)

9028

9029

Take a slice of the tuple pointed to by *p* from *low* to *high* and return it

9030

as a new tuple.

9031

9032

.. versionchanged:: 2.5

9033

- This function used an :ctype:`int` type for *low* and *high*. This might

9034

+ This function used an :c:type:`int` type for *low* and *high*. This might

9035

require changes in your code for properly supporting 64-bit systems.

9036

9037

9038

-.. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

9039

+.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

9040

9041

Insert a reference to object *o* at position *pos* of the tuple pointed to by

9042

*p*. Return ``0`` on success.

9043

@@ -118,13 +118,13 @@

9044

This function "steals" a reference to *o*.

9045

9046

.. versionchanged:: 2.5

9047

- This function used an :ctype:`int` type for *pos*. This might require

9048

+ This function used an :c:type:`int` type for *pos*. This might require

9049

changes in your code for properly supporting 64-bit systems.

9050

9051

9052

-.. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)

9053

+.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)

9054

9055

- Like :cfunc:`PyTuple_SetItem`, but does no error checking, and should *only* be

9056

+ Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be

9057

used to fill in brand new tuples.

9058

9059

.. note::

9060

@@ -132,11 +132,11 @@

9061

This function "steals" a reference to *o*.

9062

9063

.. versionchanged:: 2.5

9064

- This function used an :ctype:`int` type for *pos*. This might require

9065

+ This function used an :c:type:`int` type for *pos*. This might require

9066

changes in your code for properly supporting 64-bit systems.

9067

9068

9069

-.. cfunction:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

9070

+.. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

9071

9072

Can be used to resize a tuple. *newsize* will be the new length of the tuple.

9073

Because tuples are *supposed* to be immutable, this should only be used if there

9074

@@ -153,11 +153,11 @@

9075

Removed unused third parameter, *last_is_sticky*.

9076

9077

.. versionchanged:: 2.5

9078

- This function used an :ctype:`int` type for *newsize*. This might

9079

+ This function used an :c:type:`int` type for *newsize*. This might

9080

require changes in your code for properly supporting 64-bit systems.

9081

9082

9083

-.. cfunction:: int PyTuple_ClearFreeList()

9084

+.. c:function:: int PyTuple_ClearFreeList()

9085

9086

Clear the free list. Return the total number of freed items.

9087

9088

diff -r 8527427914a2 Doc/c-api/type.rst

9089

--- a/Doc/c-api/type.rst

9090

+++ b/Doc/c-api/type.rst

9091

@@ -8,12 +8,12 @@

9092

.. index:: object: type

9093

9094

9095

-.. ctype:: PyTypeObject

9096

+.. c:type:: PyTypeObject

9097

9098

The C structure of the objects used to describe built-in types.

9099

9100

9101

-.. cvar:: PyObject* PyType_Type

9102

+.. c:var:: PyObject* PyType_Type

9103

9104

.. index:: single: TypeType (in module types)

9105

9106

@@ -21,13 +21,13 @@

9107

``types.TypeType`` in the Python layer.

9108

9109

9110

-.. cfunction:: int PyType_Check(PyObject *o)

9111

+.. c:function:: int PyType_Check(PyObject *o)

9112

9113

Return true if the object *o* is a type object, including instances of types

9114

derived from the standard type object. Return false in all other cases.

9115

9116

9117

-.. cfunction:: int PyType_CheckExact(PyObject *o)

9118

+.. c:function:: int PyType_CheckExact(PyObject *o)

9119

9120

Return true if the object *o* is a type object, but not a subtype of the

9121

standard type object. Return false in all other cases.

9122

@@ -35,14 +35,14 @@

9123

.. versionadded:: 2.2

9124

9125

9126

-.. cfunction:: unsigned int PyType_ClearCache()

9127

+.. c:function:: unsigned int PyType_ClearCache()

9128

9129

Clear the internal lookup cache. Return the current version tag.

9130

9131

.. versionadded:: 2.6

9132

9133

9134

-.. cfunction:: void PyType_Modified(PyTypeObject *type)

9135

+.. c:function:: void PyType_Modified(PyTypeObject *type)

9136

9137

Invalidate the internal lookup cache for the type and all of its

9138

subtypes. This function must be called after any manual

9139

@@ -51,13 +51,13 @@

9140

.. versionadded:: 2.6

9141

9142

9143

-.. cfunction:: int PyType_HasFeature(PyObject *o, int feature)

9144

+.. c:function:: int PyType_HasFeature(PyObject *o, int feature)

9145

9146

Return true if the type object *o* sets the feature *feature*. Type features

9147

are denoted by single bit flags.

9148

9149

9150

-.. cfunction:: int PyType_IS_GC(PyObject *o)

9151

+.. c:function:: int PyType_IS_GC(PyObject *o)

9152

9153

Return true if the type object includes support for the cycle detector; this

9154

tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.

9155

@@ -65,28 +65,28 @@

9156

.. versionadded:: 2.0

9157

9158

9159

-.. cfunction:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)

9160

+.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)

9161

9162

Return true if *a* is a subtype of *b*.

9163

9164

.. versionadded:: 2.2

9165

9166

9167

-.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

9168

+.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

9169

9170

.. versionadded:: 2.2

9171

9172

.. versionchanged:: 2.5

9173

- This function used an :ctype:`int` type for *nitems*. This might require

9174

+ This function used an :c:type:`int` type for *nitems*. This might require

9175

changes in your code for properly supporting 64-bit systems.

9176

9177

9178

-.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)

9179

+.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)

9180

9181

.. versionadded:: 2.2

9182

9183

9184

-.. cfunction:: int PyType_Ready(PyTypeObject *type)

9185

+.. c:function:: int PyType_Ready(PyTypeObject *type)

9186

9187

Finalize a type object. This should be called on all type objects to finish

9188

their initialization. This function is responsible for adding inherited slots

9189

diff -r 8527427914a2 Doc/c-api/typeobj.rst

9190

--- a/Doc/c-api/typeobj.rst

9191

+++ b/Doc/c-api/typeobj.rst

9192

@@ -6,9 +6,9 @@

9193

============

9194

9195

Perhaps one of the most important structures of the Python object system is the

9196

-structure that defines a new type: the :ctype:`PyTypeObject` structure. Type

9197

-objects can be handled using any of the :cfunc:`PyObject_\*` or

9198

-:cfunc:`PyType_\*` functions, but do not offer much that's interesting to most

9199

+structure that defines a new type: the :c:type:`PyTypeObject` structure. Type

9200

+objects can be handled using any of the :c:func:`PyObject_\*` or

9201

+:c:func:`PyType_\*` functions, but do not offer much that's interesting to most

9202

Python applications. These objects are fundamental to how objects behave, so

9203

they are very important to the interpreter itself and to any extension module

9204

that implements new types.

9205

@@ -25,21 +25,21 @@

9206

freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc,

9207

cmpfunc, reprfunc, hashfunc

9208

9209

-The structure definition for :ctype:`PyTypeObject` can be found in

9210

+The structure definition for :c:type:`PyTypeObject` can be found in

9211

:file:`Include/object.h`. For convenience of reference, this repeats the

9212

definition found there:

9213

9214

.. literalinclude:: ../includes/typestruct.h

9215

9216

9217

-The type object structure extends the :ctype:`PyVarObject` structure. The

9218

+The type object structure extends the :c:type:`PyVarObject` structure. The

9219

:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`,

9220

-usually called from a class statement). Note that :cdata:`PyType_Type` (the

9221

+usually called from a class statement). Note that :c:data:`PyType_Type` (the

9222

metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e.

9223

type objects) *must* have the :attr:`ob_size` field.

9224

9225

9226

-.. cmember:: PyObject* PyObject._ob_next

9227

+.. c:member:: PyObject* PyObject._ob_next

9228

PyObject* PyObject._ob_prev

9229

9230

These fields are only present when the macro ``Py_TRACE_REFS`` is defined.

9231

@@ -54,7 +54,7 @@

9232

These fields are not inherited by subtypes.

9233

9234

9235

-.. cmember:: Py_ssize_t PyObject.ob_refcnt

9236

+.. c:member:: Py_ssize_t PyObject.ob_refcnt

9237

9238

This is the type object's reference count, initialized to ``1`` by the

9239

``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects,

9240

@@ -65,11 +65,11 @@

9241

This field is not inherited by subtypes.

9242

9243

.. versionchanged:: 2.5

9244

- This field used to be an :ctype:`int` type. This might require changes

9245

+ This field used to be an :c:type:`int` type. This might require changes

9246

in your code for properly supporting 64-bit systems.

9247

9248

9249

-.. cmember:: PyTypeObject* PyObject.ob_type

9250

+.. c:member:: PyTypeObject* PyObject.ob_type

9251

9252

This is the type's type, in other words its metatype. It is initialized by the

9253

argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be

9254

@@ -83,16 +83,16 @@

9255

Foo_Type.ob_type = &PyType_Type;

9256

9257

This should be done before any instances of the type are created.

9258

- :cfunc:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,

9259

+ :c:func:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,

9260

initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1

9261

and later it is initialized to the :attr:`ob_type` field of the base class.

9262

- :cfunc:`PyType_Ready` will not change this field if it is non-zero.

9263

+ :c:func:`PyType_Ready` will not change this field if it is non-zero.

9264

9265

In Python 2.2, this field is not inherited by subtypes. In 2.2.1, and in 2.3

9266

and beyond, it is inherited by subtypes.

9267

9268

9269

-.. cmember:: Py_ssize_t PyVarObject.ob_size

9270

+.. c:member:: Py_ssize_t PyVarObject.ob_size

9271

9272

For statically allocated type objects, this should be initialized to zero. For

9273

dynamically allocated type objects, this field has a special internal meaning.

9274

@@ -100,7 +100,7 @@

9275

This field is not inherited by subtypes.

9276

9277

9278

-.. cmember:: char* PyTypeObject.tp_name

9279

+.. c:member:: char* PyTypeObject.tp_name

9280

9281

Pointer to a NUL-terminated string containing the name of the type. For types

9282

that are accessible as module globals, the string should be the full module

9283

@@ -127,7 +127,7 @@

9284

This field is not inherited by subtypes.

9285

9286

9287

-.. cmember:: Py_ssize_t PyTypeObject.tp_basicsize

9288

+.. c:member:: Py_ssize_t PyTypeObject.tp_basicsize

9289

Py_ssize_t PyTypeObject.tp_itemsize

9290

9291

These fields allow calculating the size in bytes of instances of the type.

9292

@@ -149,7 +149,7 @@

9293

field).

9294

9295

The basic size includes the fields in the instance declared by the macro

9296

- :cmacro:`PyObject_HEAD` or :cmacro:`PyObject_VAR_HEAD` (whichever is used to

9297

+ :c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to

9298

declare the instance struct) and this in turn includes the :attr:`_ob_prev` and

9299

:attr:`_ob_next` fields if they are present. This means that the only correct

9300

way to get an initializer for the :attr:`tp_basicsize` is to use the

9301

@@ -170,14 +170,14 @@

9302

alignment requirement for ``double``).

9303

9304

9305

-.. cmember:: destructor PyTypeObject.tp_dealloc

9306

+.. c:member:: destructor PyTypeObject.tp_dealloc

9307

9308

A pointer to the instance destructor function. This function must be defined

9309

unless the type guarantees that its instances will never be deallocated (as is

9310

the case for the singletons ``None`` and ``Ellipsis``).

9311

9312

- The destructor function is called by the :cfunc:`Py_DECREF` and

9313

- :cfunc:`Py_XDECREF` macros when the new reference count is zero. At this point,

9314

+ The destructor function is called by the :c:func:`Py_DECREF` and

9315

+ :c:func:`Py_XDECREF` macros when the new reference count is zero. At this point,

9316

the instance is still in existence, but there are no references to it. The

9317

destructor function should free all references which the instance owns, free all

9318

memory buffers owned by the instance (using the freeing function corresponding

9319

@@ -186,15 +186,15 @@

9320

subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is

9321

permissible to call the object deallocator directly instead of via

9322

:attr:`tp_free`. The object deallocator should be the one used to allocate the

9323

- instance; this is normally :cfunc:`PyObject_Del` if the instance was allocated

9324

- using :cfunc:`PyObject_New` or :cfunc:`PyObject_VarNew`, or

9325

- :cfunc:`PyObject_GC_Del` if the instance was allocated using

9326

- :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_NewVar`.

9327

+ instance; this is normally :c:func:`PyObject_Del` if the instance was allocated

9328

+ using :c:func:`PyObject_New` or :c:func:`PyObject_VarNew`, or

9329

+ :c:func:`PyObject_GC_Del` if the instance was allocated using

9330

+ :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`.

9331

9332

This field is inherited by subtypes.

9333

9334

9335

-.. cmember:: printfunc PyTypeObject.tp_print

9336

+.. c:member:: printfunc PyTypeObject.tp_print

9337

9338

An optional pointer to the instance print function.

9339

9340

@@ -205,7 +205,7 @@

9341

*NULL*. A type should never implement :attr:`tp_print` in a way that produces

9342

different output than :attr:`tp_repr` or :attr:`tp_str` would.

9343

9344

- The print function is called with the same signature as :cfunc:`PyObject_Print`:

9345

+ The print function is called with the same signature as :c:func:`PyObject_Print`:

9346

``int tp_print(PyObject *self, FILE *file, int flags)``. The *self* argument is

9347

the instance to be printed. The *file* argument is the stdio file to which it

9348

is to be printed. The *flags* argument is composed of flag bits. The only flag

9349

@@ -223,39 +223,39 @@

9350

This field is inherited by subtypes.

9351

9352

9353

-.. cmember:: getattrfunc PyTypeObject.tp_getattr

9354

+.. c:member:: getattrfunc PyTypeObject.tp_getattr

9355

9356

An optional pointer to the get-attribute-string function.

9357

9358

This field is deprecated. When it is defined, it should point to a function

9359

that acts the same as the :attr:`tp_getattro` function, but taking a C string

9360

instead of a Python string object to give the attribute name. The signature is

9361

- the same as for :cfunc:`PyObject_GetAttrString`.

9362

+ the same as for :c:func:`PyObject_GetAttrString`.

9363

9364

This field is inherited by subtypes together with :attr:`tp_getattro`: a subtype

9365

inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when

9366

the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.

9367

9368

9369

-.. cmember:: setattrfunc PyTypeObject.tp_setattr

9370

+.. c:member:: setattrfunc PyTypeObject.tp_setattr

9371

9372

An optional pointer to the set-attribute-string function.

9373

9374

This field is deprecated. When it is defined, it should point to a function

9375

that acts the same as the :attr:`tp_setattro` function, but taking a C string

9376

instead of a Python string object to give the attribute name. The signature is

9377

- the same as for :cfunc:`PyObject_SetAttrString`.

9378

+ the same as for :c:func:`PyObject_SetAttrString`.

9379

9380

This field is inherited by subtypes together with :attr:`tp_setattro`: a subtype

9381

inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when

9382

the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.

9383

9384

9385

-.. cmember:: cmpfunc PyTypeObject.tp_compare

9386

+.. c:member:: cmpfunc PyTypeObject.tp_compare

9387

9388

An optional pointer to the three-way comparison function.

9389

9390

- The signature is the same as for :cfunc:`PyObject_Compare`. The function should

9391

+ The signature is the same as for :c:func:`PyObject_Compare`. The function should

9392

return ``1`` if *self* greater than *other*, ``0`` if *self* is equal to

9393

*other*, and ``-1`` if *self* less than *other*. It should return ``-1`` and

9394

set an exception condition when an error occurred during the comparison.

9395

@@ -266,14 +266,14 @@

9396

:attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*.

9397

9398

9399

-.. cmember:: reprfunc PyTypeObject.tp_repr

9400

+.. c:member:: reprfunc PyTypeObject.tp_repr

9401

9402

.. index:: builtin: repr

9403

9404

An optional pointer to a function that implements the built-in function

9405

:func:`repr`.

9406

9407

- The signature is the same as for :cfunc:`PyObject_Repr`; it must return a string

9408

+ The signature is the same as for :c:func:`PyObject_Repr`; it must return a string

9409

or a Unicode object. Ideally, this function should return a string that, when

9410

passed to :func:`eval`, given a suitable environment, returns an object with the

9411

same value. If this is not feasible, it should return a string starting with

9412

@@ -286,7 +286,7 @@

9413

9414

This field is inherited by subtypes.

9415

9416

-.. cmember:: PyNumberMethods* tp_as_number

9417

+.. c:member:: PyNumberMethods* tp_as_number

9418

9419

Pointer to an additional structure that contains fields relevant only to

9420

objects which implement the number protocol. These fields are documented in

9421

@@ -296,7 +296,7 @@

9422

inherited individually.

9423

9424

9425

-.. cmember:: PySequenceMethods* tp_as_sequence

9426

+.. c:member:: PySequenceMethods* tp_as_sequence

9427

9428

Pointer to an additional structure that contains fields relevant only to

9429

objects which implement the sequence protocol. These fields are documented

9430

@@ -306,7 +306,7 @@

9431

are inherited individually.

9432

9433

9434

-.. cmember:: PyMappingMethods* tp_as_mapping

9435

+.. c:member:: PyMappingMethods* tp_as_mapping

9436

9437

Pointer to an additional structure that contains fields relevant only to

9438

objects which implement the mapping protocol. These fields are documented in

9439

@@ -316,25 +316,25 @@

9440

are inherited individually.

9441

9442

9443

-.. cmember:: hashfunc PyTypeObject.tp_hash

9444

+.. c:member:: hashfunc PyTypeObject.tp_hash

9445

9446

.. index:: builtin: hash

9447

9448

An optional pointer to a function that implements the built-in function

9449

:func:`hash`.

9450

9451

- The signature is the same as for :cfunc:`PyObject_Hash`; it must return a C

9452

+ The signature is the same as for :c:func:`PyObject_Hash`; it must return a C

9453

long. The value ``-1`` should not be returned as a normal return value; when an

9454

error occurs during the computation of the hash value, the function should set

9455

an exception and return ``-1``.

9456

9457

- This field can be set explicitly to :cfunc:`PyObject_HashNotImplemented` to

9458

+ This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to

9459

block inheritance of the hash method from a parent type. This is interpreted

9460

as the equivalent of ``__hash__ = None`` at the Python level, causing

9461

``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note

9462

that the converse is also true - setting ``__hash__ = None`` on a class at

9463

the Python level will result in the ``tp_hash`` slot being set to

9464

- :cfunc:`PyObject_HashNotImplemented`.

9465

+ :c:func:`PyObject_HashNotImplemented`.

9466

9467

When this field is not set, two possibilities exist: if the :attr:`tp_compare`

9468

and :attr:`tp_richcompare` fields are both *NULL*, a default hash value based on

9469

@@ -346,39 +346,39 @@

9470

:attr:`tp_compare`, :attr:`tp_richcompare` and :attr:`tp_hash` are all *NULL*.

9471

9472

9473

-.. cmember:: ternaryfunc PyTypeObject.tp_call

9474

+.. c:member:: ternaryfunc PyTypeObject.tp_call

9475

9476

An optional pointer to a function that implements calling the object. This

9477

should be *NULL* if the object is not callable. The signature is the same as

9478

- for :cfunc:`PyObject_Call`.

9479

+ for :c:func:`PyObject_Call`.

9480

9481

This field is inherited by subtypes.

9482

9483

9484

-.. cmember:: reprfunc PyTypeObject.tp_str

9485

+.. c:member:: reprfunc PyTypeObject.tp_str

9486

9487

An optional pointer to a function that implements the built-in operation

9488

:func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the

9489

- constructor for that type. This constructor calls :cfunc:`PyObject_Str` to do

9490

- the actual work, and :cfunc:`PyObject_Str` will call this handler.)

9491

+ constructor for that type. This constructor calls :c:func:`PyObject_Str` to do

9492

+ the actual work, and :c:func:`PyObject_Str` will call this handler.)

9493

9494

- The signature is the same as for :cfunc:`PyObject_Str`; it must return a string

9495

+ The signature is the same as for :c:func:`PyObject_Str`; it must return a string

9496

or a Unicode object. This function should return a "friendly" string

9497

representation of the object, as this is the representation that will be used by

9498

the print statement.

9499

9500

- When this field is not set, :cfunc:`PyObject_Repr` is called to return a string

9501

+ When this field is not set, :c:func:`PyObject_Repr` is called to return a string

9502

representation.

9503

9504

This field is inherited by subtypes.

9505

9506

9507

-.. cmember:: getattrofunc PyTypeObject.tp_getattro

9508

+.. c:member:: getattrofunc PyTypeObject.tp_getattro

9509

9510

An optional pointer to the get-attribute function.

9511

9512

- The signature is the same as for :cfunc:`PyObject_GetAttr`. It is usually

9513

- convenient to set this field to :cfunc:`PyObject_GenericGetAttr`, which

9514

+ The signature is the same as for :c:func:`PyObject_GetAttr`. It is usually

9515

+ convenient to set this field to :c:func:`PyObject_GenericGetAttr`, which

9516

implements the normal way of looking for object attributes.

9517

9518

This field is inherited by subtypes together with :attr:`tp_getattr`: a subtype

9519

@@ -386,12 +386,12 @@

9520

the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.

9521

9522

9523

-.. cmember:: setattrofunc PyTypeObject.tp_setattro

9524

+.. c:member:: setattrofunc PyTypeObject.tp_setattro

9525

9526

An optional pointer to the set-attribute function.

9527

9528

- The signature is the same as for :cfunc:`PyObject_SetAttr`. It is usually

9529

- convenient to set this field to :cfunc:`PyObject_GenericSetAttr`, which

9530

+ The signature is the same as for :c:func:`PyObject_SetAttr`. It is usually

9531

+ convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which

9532

implements the normal way of setting object attributes.

9533

9534

This field is inherited by subtypes together with :attr:`tp_setattr`: a subtype

9535

@@ -399,7 +399,7 @@

9536

the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.

9537

9538

9539

-.. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer

9540

+.. c:member:: PyBufferProcs* PyTypeObject.tp_as_buffer

9541

9542

Pointer to an additional structure that contains fields relevant only to objects

9543

which implement the buffer interface. These fields are documented in

9544

@@ -409,7 +409,7 @@

9545

inherited individually.

9546

9547

9548

-.. cmember:: long PyTypeObject.tp_flags

9549

+.. c:member:: long PyTypeObject.tp_flags

9550

9551

This field is a bit mask of various flags. Some flags indicate variant

9552

semantics for certain situations; others are used to indicate that certain

9553

@@ -433,19 +433,19 @@

9554

9555

The following bit masks are currently defined; these can be ORed together using

9556

the ``|`` operator to form the value of the :attr:`tp_flags` field. The macro

9557

- :cfunc:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and

9558

+ :c:func:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and

9559

checks whether ``tp->tp_flags & f`` is non-zero.

9560

9561

9562

.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER

9563

9564

- If this bit is set, the :ctype:`PyBufferProcs` struct referenced by

9565

+ If this bit is set, the :c:type:`PyBufferProcs` struct referenced by

9566

:attr:`tp_as_buffer` has the :attr:`bf_getcharbuffer` field.

9567

9568

9569

.. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN

9570

9571

- If this bit is set, the :ctype:`PySequenceMethods` struct referenced by

9572

+ If this bit is set, the :c:type:`PySequenceMethods` struct referenced by

9573

:attr:`tp_as_sequence` has the :attr:`sq_contains` field.

9574

9575

9576

@@ -457,23 +457,23 @@

9577

9578

.. data:: Py_TPFLAGS_HAVE_INPLACEOPS

9579

9580

- If this bit is set, the :ctype:`PySequenceMethods` struct referenced by

9581

- :attr:`tp_as_sequence` and the :ctype:`PyNumberMethods` structure referenced by

9582

+ If this bit is set, the :c:type:`PySequenceMethods` struct referenced by

9583

+ :attr:`tp_as_sequence` and the :c:type:`PyNumberMethods` structure referenced by

9584

:attr:`tp_as_number` contain the fields for in-place operators. In particular,

9585

- this means that the :ctype:`PyNumberMethods` structure has the fields

9586

+ this means that the :c:type:`PyNumberMethods` structure has the fields

9587

:attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`,

9588

:attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`,

9589

:attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`,

9590

:attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`,

9591

:attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the

9592

- :ctype:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and

9593

+ :c:type:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and

9594

:attr:`sq_inplace_repeat`.

9595

9596

9597

.. data:: Py_TPFLAGS_CHECKTYPES

9598

9599

If this bit is set, the binary and ternary operations in the

9600

- :ctype:`PyNumberMethods` structure referenced by :attr:`tp_as_number` accept

9601

+ :c:type:`PyNumberMethods` structure referenced by :attr:`tp_as_number` accept

9602

arguments of arbitrary object types, and do their own type conversions if

9603

needed. If this bit is clear, those operations require that all arguments have

9604

the current type as their type, and the caller is supposed to perform a coercion

9605

@@ -532,20 +532,20 @@

9606

.. data:: Py_TPFLAGS_READY

9607

9608

This bit is set when the type object has been fully initialized by

9609

- :cfunc:`PyType_Ready`.

9610

+ :c:func:`PyType_Ready`.

9611

9612

9613

.. data:: Py_TPFLAGS_READYING

9614

9615

- This bit is set while :cfunc:`PyType_Ready` is in the process of initializing

9616

+ This bit is set while :c:func:`PyType_Ready` is in the process of initializing

9617

the type object.

9618

9619

9620

.. data:: Py_TPFLAGS_HAVE_GC

9621

9622

This bit is set when the object supports garbage collection. If this bit

9623

- is set, instances must be created using :cfunc:`PyObject_GC_New` and

9624

- destroyed using :cfunc:`PyObject_GC_Del`. More information in section

9625

+ is set, instances must be created using :c:func:`PyObject_GC_New` and

9626

+ destroyed using :c:func:`PyObject_GC_Del`. More information in section

9627

:ref:`supporting-cycle-detection`. This bit also implies that the

9628

GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in

9629

the type object; but those fields also exist when

9630

@@ -563,7 +563,7 @@

9631

:const:`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`.

9632

9633

9634

-.. cmember:: char* PyTypeObject.tp_doc

9635

+.. c:member:: char* PyTypeObject.tp_doc

9636

9637

An optional pointer to a NUL-terminated C string giving the docstring for this

9638

type object. This is exposed as the :attr:`__doc__` attribute on the type and

9639

@@ -575,7 +575,7 @@

9640

:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set.

9641

9642

9643

-.. cmember:: traverseproc PyTypeObject.tp_traverse

9644

+.. c:member:: traverseproc PyTypeObject.tp_traverse

9645

9646

An optional pointer to a traversal function for the garbage collector. This is

9647

only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. More information

9648

@@ -584,8 +584,8 @@

9649

9650

The :attr:`tp_traverse` pointer is used by the garbage collector to detect

9651

reference cycles. A typical implementation of a :attr:`tp_traverse` function

9652

- simply calls :cfunc:`Py_VISIT` on each of the instance's members that are Python

9653

- objects. For example, this is function :cfunc:`local_traverse` from the

9654

+ simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python

9655

+ objects. For example, this is function :c:func:`local_traverse` from the

9656

:mod:`thread` extension module::

9657

9658

static int

9659

@@ -597,7 +597,7 @@

9660

return 0;

9661

}

9662

9663

- Note that :cfunc:`Py_VISIT` is called only on those members that can participate

9664

+ Note that :c:func:`Py_VISIT` is called only on those members that can participate

9665

in reference cycles. Although there is also a ``self->key`` member, it can only

9666

be *NULL* or a Python string and therefore cannot be part of a reference cycle.

9667

9668

@@ -605,8 +605,8 @@

9669

debugging aid you may want to visit it anyway just so the :mod:`gc` module's

9670

:func:`get_referents` function will include it.

9671

9672

- Note that :cfunc:`Py_VISIT` requires the *visit* and *arg* parameters to

9673

- :cfunc:`local_traverse` to have these specific names; don't name them just

9674

+ Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to

9675

+ :c:func:`local_traverse` to have these specific names; don't name them just

9676

anything.

9677

9678

This field is inherited by subtypes together with :attr:`tp_clear` and the

9679

@@ -616,7 +616,7 @@

9680

bit set.

9681

9682

9683

-.. cmember:: inquiry PyTypeObject.tp_clear

9684

+.. c:member:: inquiry PyTypeObject.tp_clear

9685

9686

An optional pointer to a clear function for the garbage collector. This is only

9687

used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set.

9688

@@ -645,7 +645,7 @@

9689

return 0;

9690

}

9691

9692

- The :cfunc:`Py_CLEAR` macro should be used, because clearing references is

9693

+ The :c:func:`Py_CLEAR` macro should be used, because clearing references is

9694

delicate: the reference to the contained object must not be decremented until

9695

after the pointer to the contained object is set to *NULL*. This is because

9696

decrementing the reference count may cause the contained object to become trash,

9697

@@ -654,7 +654,7 @@

9698

contained object). If it's possible for such code to reference *self* again,

9699

it's important that the pointer to the contained object be *NULL* at that time,

9700

so that *self* knows the contained object can no longer be used. The

9701

- :cfunc:`Py_CLEAR` macro performs the operations in a safe order.

9702

+ :c:func:`Py_CLEAR` macro performs the operations in a safe order.

9703

9704

Because the goal of :attr:`tp_clear` functions is to break reference cycles,

9705

it's not necessary to clear contained objects like Python strings or Python

9706

@@ -672,7 +672,7 @@

9707

bit set.

9708

9709

9710

-.. cmember:: richcmpfunc PyTypeObject.tp_richcompare

9711

+.. c:member:: richcmpfunc PyTypeObject.tp_richcompare

9712

9713

An optional pointer to the rich comparison function, whose signature is

9714

``PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)``.

9715

@@ -694,7 +694,7 @@

9716

:attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*.

9717

9718

The following constants are defined to be used as the third argument for

9719

- :attr:`tp_richcompare` and for :cfunc:`PyObject_RichCompare`:

9720

+ :attr:`tp_richcompare` and for :c:func:`PyObject_RichCompare`:

9721

9722

+----------------+------------+

9723

| Constant | Comparison |

9724

@@ -716,13 +716,13 @@

9725

The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is

9726

set.

9727

9728

-.. cmember:: long PyTypeObject.tp_weaklistoffset

9729

+.. c:member:: long PyTypeObject.tp_weaklistoffset

9730

9731

If the instances of this type are weakly referenceable, this field is greater

9732

than zero and contains the offset in the instance structure of the weak

9733

reference list head (ignoring the GC header, if present); this offset is used by

9734

- :cfunc:`PyObject_ClearWeakRefs` and the :cfunc:`PyWeakref_\*` functions. The

9735

- instance structure needs to include a field of type :ctype:`PyObject\*` which is

9736

+ :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The

9737

+ instance structure needs to include a field of type :c:type:`PyObject\*` which is

9738

initialized to *NULL*.

9739

9740

Do not confuse this field with :attr:`tp_weaklist`; that is the list head for

9741

@@ -751,19 +751,19 @@

9742

set.

9743

9744

9745

-.. cmember:: getiterfunc PyTypeObject.tp_iter

9746

+.. c:member:: getiterfunc PyTypeObject.tp_iter

9747

9748

An optional pointer to a function that returns an iterator for the object. Its

9749

presence normally signals that the instances of this type are iterable (although

9750

sequences may be iterable without this function, and classic instances always

9751

have this function, even if they don't define an :meth:`__iter__` method).

9752

9753

- This function has the same signature as :cfunc:`PyObject_GetIter`.

9754

+ This function has the same signature as :c:func:`PyObject_GetIter`.

9755

9756

This field is inherited by subtypes.

9757

9758

9759

-.. cmember:: iternextfunc PyTypeObject.tp_iternext

9760

+.. c:member:: iternextfunc PyTypeObject.tp_iternext

9761

9762

An optional pointer to a function that returns the next item in an iterator.

9763

When the iterator is exhausted, it must return *NULL*; a :exc:`StopIteration`

9764

@@ -776,7 +776,7 @@

9765

function should return the iterator instance itself (not a new iterator

9766

instance).

9767

9768

- This function has the same signature as :cfunc:`PyIter_Next`.

9769

+ This function has the same signature as :c:func:`PyIter_Next`.

9770

9771

This field is inherited by subtypes.

9772

9773

@@ -784,9 +784,9 @@

9774

:const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set.

9775

9776

9777

-.. cmember:: struct PyMethodDef* PyTypeObject.tp_methods

9778

+.. c:member:: struct PyMethodDef* PyTypeObject.tp_methods

9779

9780

- An optional pointer to a static *NULL*-terminated array of :ctype:`PyMethodDef`

9781

+ An optional pointer to a static *NULL*-terminated array of :c:type:`PyMethodDef`

9782

structures, declaring regular methods of this type.

9783

9784

For each entry in the array, an entry is added to the type's dictionary (see

9785

@@ -796,9 +796,9 @@

9786

different mechanism).

9787

9788

9789

-.. cmember:: struct PyMemberDef* PyTypeObject.tp_members

9790

+.. c:member:: struct PyMemberDef* PyTypeObject.tp_members

9791

9792

- An optional pointer to a static *NULL*-terminated array of :ctype:`PyMemberDef`

9793

+ An optional pointer to a static *NULL*-terminated array of :c:type:`PyMemberDef`

9794

structures, declaring regular data members (fields or slots) of instances of

9795

this type.

9796

9797

@@ -809,9 +809,9 @@

9798

different mechanism).

9799

9800

9801

-.. cmember:: struct PyGetSetDef* PyTypeObject.tp_getset

9802

+.. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset

9803

9804

- An optional pointer to a static *NULL*-terminated array of :ctype:`PyGetSetDef`

9805

+ An optional pointer to a static *NULL*-terminated array of :c:type:`PyGetSetDef`

9806

structures, declaring computed attributes of instances of this type.

9807

9808

For each entry in the array, an entry is added to the type's dictionary (see

9809

@@ -836,7 +836,7 @@

9810

} PyGetSetDef;

9811

9812

9813

-.. cmember:: PyTypeObject* PyTypeObject.tp_base

9814

+.. c:member:: PyTypeObject* PyTypeObject.tp_base

9815

9816

An optional pointer to a base type from which type properties are inherited. At

9817

this level, only single inheritance is supported; multiple inheritance require

9818

@@ -847,13 +847,13 @@

9819

:class:`object`).

9820

9821

9822

-.. cmember:: PyObject* PyTypeObject.tp_dict

9823

+.. c:member:: PyObject* PyTypeObject.tp_dict

9824

9825

- The type's dictionary is stored here by :cfunc:`PyType_Ready`.

9826

+ The type's dictionary is stored here by :c:func:`PyType_Ready`.

9827

9828

This field should normally be initialized to *NULL* before PyType_Ready is

9829

called; it may also be initialized to a dictionary containing initial attributes

9830

- for the type. Once :cfunc:`PyType_Ready` has initialized the type, extra

9831

+ for the type. Once :c:func:`PyType_Ready` has initialized the type, extra

9832

attributes for the type may be added to this dictionary only if they don't

9833

correspond to overloaded operations (like :meth:`__add__`).

9834

9835

@@ -861,7 +861,7 @@

9836

are inherited through a different mechanism).

9837

9838

9839

-.. cmember:: descrgetfunc PyTypeObject.tp_descr_get

9840

+.. c:member:: descrgetfunc PyTypeObject.tp_descr_get

9841

9842

An optional pointer to a "descriptor get" function.

9843

9844

@@ -874,7 +874,7 @@

9845

This field is inherited by subtypes.

9846

9847

9848

-.. cmember:: descrsetfunc PyTypeObject.tp_descr_set

9849

+.. c:member:: descrsetfunc PyTypeObject.tp_descr_set

9850

9851

An optional pointer to a "descriptor set" function.

9852

9853

@@ -887,12 +887,12 @@

9854

.. XXX explain.

9855

9856

9857

-.. cmember:: long PyTypeObject.tp_dictoffset

9858

+.. c:member:: long PyTypeObject.tp_dictoffset

9859

9860

If the instances of this type have a dictionary containing instance variables,

9861

this field is non-zero and contains the offset in the instances of the type of

9862

the instance variable dictionary; this offset is used by

9863

- :cfunc:`PyObject_GenericGetAttr`.

9864

+ :c:func:`PyObject_GenericGetAttr`.

9865

9866

Do not confuse this field with :attr:`tp_dict`; that is the dictionary for

9867

attributes of the type object itself.

9868

@@ -920,7 +920,7 @@

9869

taken from the type object, and :attr:`ob_size` is taken from the instance. The

9870

absolute value is taken because long ints use the sign of :attr:`ob_size` to

9871

store the sign of the number. (There's never a need to do this calculation

9872

- yourself; it is done for you by :cfunc:`_PyObject_GetDictPtr`.)

9873

+ yourself; it is done for you by :c:func:`_PyObject_GetDictPtr`.)

9874

9875

This field is inherited by subtypes, but see the rules listed below. A subtype

9876

may override this offset; this means that the subtype instances store the

9877

@@ -940,7 +940,7 @@

9878

added as a feature just like :attr:`__weakref__` though.)

9879

9880

9881

-.. cmember:: initproc PyTypeObject.tp_init

9882

+.. c:member:: initproc PyTypeObject.tp_init

9883

9884

An optional pointer to an instance initialization function.

9885

9886

@@ -970,7 +970,7 @@

9887

This field is inherited by subtypes.

9888

9889

9890

-.. cmember:: allocfunc PyTypeObject.tp_alloc

9891

+.. c:member:: allocfunc PyTypeObject.tp_alloc

9892

9893

An optional pointer to an instance allocation function.

9894

9895

@@ -993,11 +993,11 @@

9896

9897

This field is inherited by static subtypes, but not by dynamic subtypes

9898

(subtypes created by a class statement); in the latter, this field is always set

9899

- to :cfunc:`PyType_GenericAlloc`, to force a standard heap allocation strategy.

9900

+ to :c:func:`PyType_GenericAlloc`, to force a standard heap allocation strategy.

9901

That is also the recommended value for statically defined types.

9902

9903

9904

-.. cmember:: newfunc PyTypeObject.tp_new

9905

+.. c:member:: newfunc PyTypeObject.tp_new

9906

9907

An optional pointer to an instance creation function.

9908

9909

@@ -1029,16 +1029,16 @@

9910

being linked with Python 2.2.

9911

9912

9913

-.. cmember:: destructor PyTypeObject.tp_free

9914

+.. c:member:: destructor PyTypeObject.tp_free

9915

9916

An optional pointer to an instance deallocation function.

9917

9918

The signature of this function has changed slightly: in Python 2.2 and 2.2.1,

9919

- its signature is :ctype:`destructor`::

9920

+ its signature is :c:type:`destructor`::

9921

9922

void tp_free(PyObject *)

9923

9924

- In Python 2.3 and beyond, its signature is :ctype:`freefunc`::

9925

+ In Python 2.3 and beyond, its signature is :c:type:`freefunc`::

9926

9927

void tp_free(void *)

9928

9929

@@ -1047,11 +1047,11 @@

9930

9931

This field is inherited by static subtypes, but not by dynamic subtypes

9932

(subtypes created by a class statement); in the latter, this field is set to a

9933

- deallocator suitable to match :cfunc:`PyType_GenericAlloc` and the value of the

9934

+ deallocator suitable to match :c:func:`PyType_GenericAlloc` and the value of the

9935

:const:`Py_TPFLAGS_HAVE_GC` flag bit.

9936

9937

9938

-.. cmember:: inquiry PyTypeObject.tp_is_gc

9939

+.. c:member:: inquiry PyTypeObject.tp_is_gc

9940

9941

An optional pointer to a function called by the garbage collector.

9942

9943

@@ -1066,14 +1066,14 @@

9944

int tp_is_gc(PyObject *self)

9945

9946

(The only example of this are types themselves. The metatype,

9947

- :cdata:`PyType_Type`, defines this function to distinguish between statically

9948

+ :c:data:`PyType_Type`, defines this function to distinguish between statically

9949

and dynamically allocated types.)

9950

9951

This field is inherited by subtypes. (VERSION NOTE: in Python 2.2, it was not

9952

inherited. It is inherited in 2.2.1 and later versions.)

9953

9954

9955

-.. cmember:: PyObject* PyTypeObject.tp_bases

9956

+.. c:member:: PyObject* PyTypeObject.tp_bases

9957

9958

Tuple of base types.

9959

9960

@@ -1083,25 +1083,25 @@

9961

This field is not inherited.

9962

9963

9964

-.. cmember:: PyObject* PyTypeObject.tp_mro

9965

+.. c:member:: PyObject* PyTypeObject.tp_mro

9966

9967

Tuple containing the expanded set of base types, starting with the type itself

9968

and ending with :class:`object`, in Method Resolution Order.

9969

9970

- This field is not inherited; it is calculated fresh by :cfunc:`PyType_Ready`.

9971

+ This field is not inherited; it is calculated fresh by :c:func:`PyType_Ready`.

9972

9973

9974

-.. cmember:: PyObject* PyTypeObject.tp_cache

9975

+.. c:member:: PyObject* PyTypeObject.tp_cache

9976

9977

Unused. Not inherited. Internal use only.

9978

9979

9980

-.. cmember:: PyObject* PyTypeObject.tp_subclasses

9981

+.. c:member:: PyObject* PyTypeObject.tp_subclasses

9982

9983

List of weak references to subclasses. Not inherited. Internal use only.

9984

9985

9986

-.. cmember:: PyObject* PyTypeObject.tp_weaklist

9987

+.. c:member:: PyObject* PyTypeObject.tp_weaklist

9988

9989

Weak reference list head, for weak references to this type object. Not

9990

inherited. Internal use only.

9991

@@ -1112,22 +1112,22 @@

9992

subtypes.

9993

9994

9995

-.. cmember:: Py_ssize_t PyTypeObject.tp_allocs

9996

+.. c:member:: Py_ssize_t PyTypeObject.tp_allocs

9997

9998

Number of allocations.

9999

10000

10001

-.. cmember:: Py_ssize_t PyTypeObject.tp_frees

10002

+.. c:member:: Py_ssize_t PyTypeObject.tp_frees

10003

10004

Number of frees.

10005

10006

10007

-.. cmember:: Py_ssize_t PyTypeObject.tp_maxalloc

10008

+.. c:member:: Py_ssize_t PyTypeObject.tp_maxalloc

10009

10010

Maximum simultaneously allocated objects.

10011

10012

10013

-.. cmember:: PyTypeObject* PyTypeObject.tp_next

10014

+.. c:member:: PyTypeObject* PyTypeObject.tp_next

10015

10016

Pointer to the next type object with a non-zero :attr:`tp_allocs` field.

10017

10018

@@ -1150,7 +1150,7 @@

10019

.. sectionauthor:: Amaury Forgeot d'Arc

10020

10021

10022

-.. ctype:: PyNumberMethods

10023

+.. c:type:: PyNumberMethods

10024

10025

This structure holds pointers to the functions which an object uses to

10026

implement the number protocol. Almost every function below is used by the

10027

@@ -1215,9 +1215,9 @@

10028

the coercion method specified by the :attr:`nb_coerce` member to convert the

10029

arguments:

10030

10031

- .. cmember:: coercion PyNumberMethods.nb_coerce

10032

+ .. c:member:: coercion PyNumberMethods.nb_coerce

10033

10034

- This function is used by :cfunc:`PyNumber_CoerceEx` and has the same

10035

+ This function is used by :c:func:`PyNumber_CoerceEx` and has the same

10036

signature. The first argument is always a pointer to an object of the

10037

defined type. If the conversion to a common "larger" type is possible, the

10038

function replaces the pointers with new references to the converted objects

10039

@@ -1243,26 +1243,26 @@

10040

.. sectionauthor:: Amaury Forgeot d'Arc

10041

10042

10043

-.. ctype:: PyMappingMethods

10044

+.. c:type:: PyMappingMethods

10045

10046

This structure holds pointers to the functions which an object uses to

10047

implement the mapping protocol. It has three members:

10048

10049

-.. cmember:: lenfunc PyMappingMethods.mp_length

10050

+.. c:member:: lenfunc PyMappingMethods.mp_length

10051

10052

- This function is used by :cfunc:`PyMapping_Length` and

10053

- :cfunc:`PyObject_Size`, and has the same signature. This slot may be set to

10054

+ This function is used by :c:func:`PyMapping_Length` and

10055

+ :c:func:`PyObject_Size`, and has the same signature. This slot may be set to

10056

*NULL* if the object has no defined length.

10057

10058

-.. cmember:: binaryfunc PyMappingMethods.mp_subscript

10059

+.. c:member:: binaryfunc PyMappingMethods.mp_subscript

10060

10061

- This function is used by :cfunc:`PyObject_GetItem` and has the same

10062

- signature. This slot must be filled for the :cfunc:`PyMapping_Check`

10063

+ This function is used by :c:func:`PyObject_GetItem` and has the same

10064

+ signature. This slot must be filled for the :c:func:`PyMapping_Check`

10065

function to return ``1``, it can be *NULL* otherwise.

10066

10067

-.. cmember:: objobjargproc PyMappingMethods.mp_ass_subscript

10068

+.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript

10069

10070

- This function is used by :cfunc:`PyObject_SetItem` and has the same

10071

+ This function is used by :c:func:`PyObject_SetItem` and has the same

10072

signature. If this slot is *NULL*, the object does not support item

10073

assignment.

10074

10075

@@ -1275,32 +1275,32 @@

10076

.. sectionauthor:: Amaury Forgeot d'Arc

10077

10078

10079

-.. ctype:: PySequenceMethods

10080

+.. c:type:: PySequenceMethods

10081

10082

This structure holds pointers to the functions which an object uses to

10083

implement the sequence protocol.

10084

10085

-.. cmember:: lenfunc PySequenceMethods.sq_length

10086

+.. c:member:: lenfunc PySequenceMethods.sq_length

10087

10088

- This function is used by :cfunc:`PySequence_Size` and :cfunc:`PyObject_Size`,

10089

+ This function is used by :c:func:`PySequence_Size` and :c:func:`PyObject_Size`,

10090

and has the same signature.

10091

10092

-.. cmember:: binaryfunc PySequenceMethods.sq_concat

10093

+.. c:member:: binaryfunc PySequenceMethods.sq_concat

10094

10095

- This function is used by :cfunc:`PySequence_Concat` and has the same

10096

+ This function is used by :c:func:`PySequence_Concat` and has the same

10097

signature. It is also used by the ``+`` operator, after trying the numeric

10098

addition via the :attr:`tp_as_number.nb_add` slot.

10099

10100

-.. cmember:: ssizeargfunc PySequenceMethods.sq_repeat

10101

+.. c:member:: ssizeargfunc PySequenceMethods.sq_repeat

10102

10103

- This function is used by :cfunc:`PySequence_Repeat` and has the same

10104

+ This function is used by :c:func:`PySequence_Repeat` and has the same

10105

signature. It is also used by the ``*`` operator, after trying numeric

10106

multiplication via the :attr:`tp_as_number.nb_mul` slot.

10107

10108

-.. cmember:: ssizeargfunc PySequenceMethods.sq_item

10109

+.. c:member:: ssizeargfunc PySequenceMethods.sq_item

10110

10111

- This function is used by :cfunc:`PySequence_GetItem` and has the same

10112

- signature. This slot must be filled for the :cfunc:`PySequence_Check`

10113

+ This function is used by :c:func:`PySequence_GetItem` and has the same

10114

+ signature. This slot must be filled for the :c:func:`PySequence_Check`

10115

function to return ``1``, it can be *NULL* otherwise.

10116

10117

Negative indexes are handled as follows: if the :attr:`sq_length` slot is

10118

@@ -1308,27 +1308,27 @@

10119

index which is passed to :attr:`sq_item`. If :attr:`sq_length` is *NULL*,

10120

the index is passed as is to the function.

10121

10122

-.. cmember:: ssizeobjargproc PySequenceMethods.sq_ass_item

10123

+.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item

10124

10125

- This function is used by :cfunc:`PySequence_SetItem` and has the same

10126

+ This function is used by :c:func:`PySequence_SetItem` and has the same

10127

signature. This slot may be left to *NULL* if the object does not support

10128

item assignment.

10129

10130

-.. cmember:: objobjproc PySequenceMethods.sq_contains

10131

+.. c:member:: objobjproc PySequenceMethods.sq_contains

10132

10133

- This function may be used by :cfunc:`PySequence_Contains` and has the same

10134

+ This function may be used by :c:func:`PySequence_Contains` and has the same

10135

signature. This slot may be left to *NULL*, in this case

10136

- :cfunc:`PySequence_Contains` simply traverses the sequence until it finds a

10137

+ :c:func:`PySequence_Contains` simply traverses the sequence until it finds a

10138

match.

10139

10140

-.. cmember:: binaryfunc PySequenceMethods.sq_inplace_concat

10141

+.. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat

10142

10143

- This function is used by :cfunc:`PySequence_InPlaceConcat` and has the same

10144

+ This function is used by :c:func:`PySequence_InPlaceConcat` and has the same

10145

signature. It should modify its first operand, and return it.

10146

10147

-.. cmember:: ssizeargfunc PySequenceMethods.sq_inplace_repeat

10148

+.. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat

10149

10150

- This function is used by :cfunc:`PySequence_InPlaceRepeat` and has the same

10151

+ This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same

10152

signature. It should modify its first operand, and return it.

10153

10154

.. XXX need to explain precedence between mapping and sequence

10155

@@ -1349,45 +1349,45 @@

10156

to be non-contiguous in memory.

10157

10158

If an object does not export the buffer interface, then its :attr:`tp_as_buffer`

10159

-member in the :ctype:`PyTypeObject` structure should be *NULL*. Otherwise, the

10160

-:attr:`tp_as_buffer` will point to a :ctype:`PyBufferProcs` structure.

10161

+member in the :c:type:`PyTypeObject` structure should be *NULL*. Otherwise, the

10162

+:attr:`tp_as_buffer` will point to a :c:type:`PyBufferProcs` structure.

10163

10164

.. note::

10165

10166

- It is very important that your :ctype:`PyTypeObject` structure uses

10167

+ It is very important that your :c:type:`PyTypeObject` structure uses

10168

:const:`Py_TPFLAGS_DEFAULT` for the value of the :attr:`tp_flags` member rather

10169

- than ``0``. This tells the Python runtime that your :ctype:`PyBufferProcs`

10170

+ than ``0``. This tells the Python runtime that your :c:type:`PyBufferProcs`

10171

structure contains the :attr:`bf_getcharbuffer` slot. Older versions of Python

10172

did not have this member, so a new Python interpreter using an old extension

10173

needs to be able to test for its presence before using it.

10174

10175

10176

-.. ctype:: PyBufferProcs

10177

+.. c:type:: PyBufferProcs

10178

10179

Structure used to hold the function pointers which define an implementation of

10180

the buffer protocol.

10181

10182

- The first slot is :attr:`bf_getreadbuffer`, of type :ctype:`getreadbufferproc`.

10183

+ The first slot is :attr:`bf_getreadbuffer`, of type :c:type:`getreadbufferproc`.

10184

If this slot is *NULL*, then the object does not support reading from the

10185

internal data. This is non-sensical, so implementors should fill this in, but

10186

callers should test that the slot contains a non-*NULL* value.

10187

10188

The next slot is :attr:`bf_getwritebuffer` having type

10189

- :ctype:`getwritebufferproc`. This slot may be *NULL* if the object does not

10190

+ :c:type:`getwritebufferproc`. This slot may be *NULL* if the object does not

10191

allow writing into its returned buffers.

10192

10193

- The third slot is :attr:`bf_getsegcount`, with type :ctype:`getsegcountproc`.

10194

+ The third slot is :attr:`bf_getsegcount`, with type :c:type:`getsegcountproc`.

10195

This slot must not be *NULL* and is used to inform the caller how many segments

10196

- the object contains. Simple objects such as :ctype:`PyString_Type` and

10197

- :ctype:`PyBuffer_Type` objects contain a single segment.

10198

+ the object contains. Simple objects such as :c:type:`PyString_Type` and

10199

+ :c:type:`PyBuffer_Type` objects contain a single segment.

10200

10201

.. index:: single: PyType_HasFeature()

10202

10203

- The last slot is :attr:`bf_getcharbuffer`, of type :ctype:`getcharbufferproc`.

10204

+ The last slot is :attr:`bf_getcharbuffer`, of type :c:type:`getcharbufferproc`.

10205

This slot will only be present if the :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`

10206

flag is present in the :attr:`tp_flags` field of the object's

10207

- :ctype:`PyTypeObject`. Before using this slot, the caller should test whether it

10208

- is present by using the :cfunc:`PyType_HasFeature` function. If the flag is

10209

+ :c:type:`PyTypeObject`. Before using this slot, the caller should test whether it

10210

+ is present by using the :c:func:`PyType_HasFeature` function. If the flag is

10211

present, :attr:`bf_getcharbuffer` may be *NULL*, indicating that the object's

10212

contents cannot be used as *8-bit characters*. The slot function may also raise

10213

an error if the object's contents cannot be interpreted as 8-bit characters.

10214

@@ -1411,7 +1411,7 @@

10215

buffer interface or that the :attr:`bf_getcharbuffer` slot is non-*NULL*.

10216

10217

10218

-.. ctype:: Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)

10219

+.. c:type:: Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)

10220

10221

Return a pointer to a readable segment of the buffer in ``*ptrptr``. This

10222

function is allowed to raise an exception, in which case it must return ``-1``.

10223

@@ -1421,7 +1421,7 @@

10224

``*ptrptr`` to a pointer to that memory.

10225

10226

10227

-.. ctype:: Py_ssize_t (*writebufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)

10228

+.. c:type:: Py_ssize_t (*writebufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)

10229

10230

Return a pointer to a writable memory buffer in ``*ptrptr``, and the length of

10231

that segment as the function return value. The memory buffer must correspond to

10232

@@ -1435,14 +1435,14 @@

10233

segment. That indicates a blatant programming error in the C code.

10234

10235

10236

-.. ctype:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp)

10237

+.. c:type:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp)

10238

10239

Return the number of memory segments which comprise the buffer. If *lenp* is

10240

not *NULL*, the implementation must report the sum of the sizes (in bytes) of

10241

all segments in ``*lenp``. The function cannot fail.

10242

10243

10244

-.. ctype:: Py_ssize_t (*charbufferproc) (PyObject *self, Py_ssize_t segment, const char **ptrptr)

10245

+.. c:type:: Py_ssize_t (*charbufferproc) (PyObject *self, Py_ssize_t segment, const char **ptrptr)

10246

10247

Return the size of the segment *segment* that *ptrptr* is set to. ``*ptrptr``

10248

is set to the memory buffer. Returns ``-1`` on error.

10249

diff -r 8527427914a2 Doc/c-api/unicode.rst

10250

--- a/Doc/c-api/unicode.rst

10251

+++ b/Doc/c-api/unicode.rst

10252

@@ -18,39 +18,39 @@

10253

Python:

10254

10255

10256

-.. ctype:: Py_UNICODE

10257

+.. c:type:: Py_UNICODE

10258

10259

This type represents the storage type which is used by Python internally as

10260

basis for holding Unicode ordinals. Python's default builds use a 16-bit type

10261

- for :ctype:`Py_UNICODE` and store Unicode values internally as UCS2. It is also

10262

+ for :c:type:`Py_UNICODE` and store Unicode values internally as UCS2. It is also

10263

possible to build a UCS4 version of Python (most recent Linux distributions come

10264

with UCS4 builds of Python). These builds then use a 32-bit type for

10265

- :ctype:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms

10266

- where :ctype:`wchar_t` is available and compatible with the chosen Python

10267

- Unicode build variant, :ctype:`Py_UNICODE` is a typedef alias for

10268

- :ctype:`wchar_t` to enhance native platform compatibility. On all other

10269

- platforms, :ctype:`Py_UNICODE` is a typedef alias for either :ctype:`unsigned

10270

- short` (UCS2) or :ctype:`unsigned long` (UCS4).

10271

+ :c:type:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms

10272

+ where :c:type:`wchar_t` is available and compatible with the chosen Python

10273

+ Unicode build variant, :c:type:`Py_UNICODE` is a typedef alias for

10274

+ :c:type:`wchar_t` to enhance native platform compatibility. On all other

10275

+ platforms, :c:type:`Py_UNICODE` is a typedef alias for either :c:type:`unsigned

10276

+ short` (UCS2) or :c:type:`unsigned long` (UCS4).

10277

10278

Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep

10279

this in mind when writing extensions or interfaces.

10280

10281

10282

-.. ctype:: PyUnicodeObject

10283

+.. c:type:: PyUnicodeObject

10284

10285

- This subtype of :ctype:`PyObject` represents a Python Unicode object.

10286

+ This subtype of :c:type:`PyObject` represents a Python Unicode object.

10287

10288

10289

-.. cvar:: PyTypeObject PyUnicode_Type

10290

+.. c:var:: PyTypeObject PyUnicode_Type

10291

10292

- This instance of :ctype:`PyTypeObject` represents the Python Unicode type. It

10293

+ This instance of :c:type:`PyTypeObject` represents the Python Unicode type. It

10294

is exposed to Python code as ``unicode`` and ``types.UnicodeType``.

10295

10296

The following APIs are really C macros and can be used to do fast checks and to

10297

access internal read-only data of Unicode objects:

10298

10299

10300

-.. cfunction:: int PyUnicode_Check(PyObject *o)

10301

+.. c:function:: int PyUnicode_Check(PyObject *o)

10302

10303

Return true if the object *o* is a Unicode object or an instance of a Unicode

10304

subtype.

10305

@@ -59,7 +59,7 @@

10306

Allowed subtypes to be accepted.

10307

10308

10309

-.. cfunction:: int PyUnicode_CheckExact(PyObject *o)

10310

+.. c:function:: int PyUnicode_CheckExact(PyObject *o)

10311

10312

Return true if the object *o* is a Unicode object, but not an instance of a

10313

subtype.

10314

@@ -67,39 +67,39 @@

10315

.. versionadded:: 2.2

10316

10317

10318

-.. cfunction:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)

10319

+.. c:function:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)

10320

10321

- Return the size of the object. *o* has to be a :ctype:`PyUnicodeObject` (not

10322

+ Return the size of the object. *o* has to be a :c:type:`PyUnicodeObject` (not

10323

checked).

10324

10325

.. versionchanged:: 2.5

10326

- This function returned an :ctype:`int` type. This might require changes

10327

+ This function returned an :c:type:`int` type. This might require changes

10328

in your code for properly supporting 64-bit systems.

10329

10330

10331

-.. cfunction:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)

10332

+.. c:function:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)

10333

10334

Return the size of the object's internal buffer in bytes. *o* has to be a

10335

- :ctype:`PyUnicodeObject` (not checked).

10336

+ :c:type:`PyUnicodeObject` (not checked).

10337

10338

.. versionchanged:: 2.5

10339

- This function returned an :ctype:`int` type. This might require changes

10340

+ This function returned an :c:type:`int` type. This might require changes

10341

in your code for properly supporting 64-bit systems.

10342

10343

10344

-.. cfunction:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)

10345

+.. c:function:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)

10346

10347

- Return a pointer to the internal :ctype:`Py_UNICODE` buffer of the object. *o*

10348

- has to be a :ctype:`PyUnicodeObject` (not checked).

10349

+ Return a pointer to the internal :c:type:`Py_UNICODE` buffer of the object. *o*

10350

+ has to be a :c:type:`PyUnicodeObject` (not checked).

10351

10352

10353

-.. cfunction:: const char* PyUnicode_AS_DATA(PyObject *o)

10354

+.. c:function:: const char* PyUnicode_AS_DATA(PyObject *o)

10355

10356

Return a pointer to the internal buffer of the object. *o* has to be a

10357

- :ctype:`PyUnicodeObject` (not checked).

10358

+ :c:type:`PyUnicodeObject` (not checked).

10359

10360

10361

-.. cfunction:: int PyUnicode_ClearFreeList()

10362

+.. c:function:: int PyUnicode_ClearFreeList()

10363

10364

Clear the free list. Return the total number of freed items.

10365

10366

@@ -114,86 +114,86 @@

10367

the Python configuration.

10368

10369

10370

-.. cfunction:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)

10371

+.. c:function:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)

10372

10373

Return 1 or 0 depending on whether *ch* is a whitespace character.

10374

10375

10376

-.. cfunction:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)

10377

+.. c:function:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)

10378

10379

Return 1 or 0 depending on whether *ch* is a lowercase character.

10380

10381

10382

-.. cfunction:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)

10383

+.. c:function:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)

10384

10385

Return 1 or 0 depending on whether *ch* is an uppercase character.

10386

10387

10388

-.. cfunction:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)

10389

+.. c:function:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)

10390

10391

Return 1 or 0 depending on whether *ch* is a titlecase character.

10392

10393

10394

-.. cfunction:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)

10395

+.. c:function:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)

10396

10397

Return 1 or 0 depending on whether *ch* is a linebreak character.

10398

10399

10400

-.. cfunction:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)

10401

+.. c:function:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)

10402

10403

Return 1 or 0 depending on whether *ch* is a decimal character.

10404

10405

10406

-.. cfunction:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)

10407

+.. c:function:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)

10408

10409

Return 1 or 0 depending on whether *ch* is a digit character.

10410

10411

10412

-.. cfunction:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)

10413

+.. c:function:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)

10414

10415

Return 1 or 0 depending on whether *ch* is a numeric character.

10416

10417

10418

-.. cfunction:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)

10419

+.. c:function:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)

10420

10421

Return 1 or 0 depending on whether *ch* is an alphabetic character.

10422

10423

10424

-.. cfunction:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)

10425

+.. c:function:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)

10426

10427

Return 1 or 0 depending on whether *ch* is an alphanumeric character.

10428

10429

These APIs can be used for fast direct character conversions:

10430

10431

10432

-.. cfunction:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)

10433

+.. c:function:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)

10434

10435

Return the character *ch* converted to lower case.

10436

10437

10438

-.. cfunction:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)

10439

+.. c:function:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)

10440

10441

Return the character *ch* converted to upper case.

10442

10443

10444

-.. cfunction:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)

10445

+.. c:function:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)

10446

10447

Return the character *ch* converted to title case.

10448

10449

10450

-.. cfunction:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)

10451

+.. c:function:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)

10452

10453

Return the character *ch* converted to a decimal positive integer. Return

10454

``-1`` if this is not possible. This macro does not raise exceptions.

10455

10456

10457

-.. cfunction:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)

10458

+.. c:function:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)

10459

10460

Return the character *ch* converted to a single digit integer. Return ``-1`` if

10461

this is not possible. This macro does not raise exceptions.

10462

10463

10464

-.. cfunction:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)

10465

+.. c:function:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)

10466

10467

Return the character *ch* converted to a double. Return ``-1.0`` if this is not

10468

possible. This macro does not raise exceptions.

10469

@@ -206,7 +206,7 @@

10470

APIs:

10471

10472

10473

-.. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)

10474

+.. c:function:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)

10475

10476

Create a Unicode object from the Py_UNICODE buffer *u* of the given size. *u*

10477

may be *NULL* which causes the contents to be undefined. It is the user's

10478

@@ -216,11 +216,11 @@

10479

is *NULL*.

10480

10481

.. versionchanged:: 2.5

10482

- This function used an :ctype:`int` type for *size*. This might require

10483

+ This function used an :c:type:`int` type for *size*. This might require

10484

changes in your code for properly supporting 64-bit systems.

10485

10486

10487

-.. cfunction:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)

10488

+.. c:function:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)

10489

10490

Create a Unicode object from the char buffer *u*. The bytes will be interpreted

10491

as being UTF-8 encoded. *u* may also be *NULL* which

10492

@@ -232,7 +232,7 @@

10493

.. versionadded:: 2.6

10494

10495

10496

-.. cfunction:: PyObject *PyUnicode_FromString(const char *u)

10497

+.. c:function:: PyObject *PyUnicode_FromString(const char *u)

10498

10499

Create a Unicode object from an UTF-8 encoded null-terminated char buffer

10500

*u*.

10501

@@ -240,9 +240,9 @@

10502

.. versionadded:: 2.6

10503

10504

10505

-.. cfunction:: PyObject* PyUnicode_FromFormat(const char *format, ...)

10506

+.. c:function:: PyObject* PyUnicode_FromFormat(const char *format, ...)

10507

10508

- Take a C :cfunc:`printf`\ -style *format* string and a variable number of

10509

+ Take a C :c:func:`printf`\ -style *format* string and a variable number of

10510

arguments, calculate the size of the resulting Python unicode string and return

10511

a string with the values formatted into it. The variable arguments must be C

10512

types and must correspond exactly to the format characters in the *format*

10513

@@ -317,7 +317,7 @@

10514

.. versionadded:: 2.6

10515

10516

10517

-.. cfunction:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)

10518

+.. c:function:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)

10519

10520

Identical to :func:`PyUnicode_FromFormat` except that it takes exactly two

10521

arguments.

10522

@@ -325,22 +325,25 @@

10523

.. versionadded:: 2.6

10524

10525

10526

-.. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)

10527

+.. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)

10528

10529

- Return a read-only pointer to the Unicode object's internal :ctype:`Py_UNICODE`

10530

- buffer, *NULL* if *unicode* is not a Unicode object.

10531

+ Return a read-only pointer to the Unicode object's internal

10532

+ :c:type:`Py_UNICODE` buffer, *NULL* if *unicode* is not a Unicode object.

10533

+ Note that the resulting :c:type:`Py_UNICODE*` string may contain embedded

10534

+ null characters, which would cause the string to be truncated when used in

10535

+ most C functions.

10536

10537

10538

-.. cfunction:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)

10539

+.. c:function:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)

10540

10541

Return the length of the Unicode object.

10542

10543

.. versionchanged:: 2.5

10544

- This function returned an :ctype:`int` type. This might require changes

10545

+ This function returned an :c:type:`int` type. This might require changes

10546

in your code for properly supporting 64-bit systems.

10547

10548

10549

-.. cfunction:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)

10550

+.. c:function:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)

10551

10552

Coerce an encoded object *obj* to an Unicode object and return a reference with

10553

incremented refcount.

10554

@@ -357,44 +360,46 @@

10555

decref'ing the returned objects.

10556

10557

10558

-.. cfunction:: PyObject* PyUnicode_FromObject(PyObject *obj)

10559

+.. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)

10560

10561

Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used

10562

throughout the interpreter whenever coercion to Unicode is needed.

10563

10564

-If the platform supports :ctype:`wchar_t` and provides a header file wchar.h,

10565

+If the platform supports :c:type:`wchar_t` and provides a header file wchar.h,

10566

Python can interface directly to this type using the following functions.

10567

-Support is optimized if Python's own :ctype:`Py_UNICODE` type is identical to

10568

-the system's :ctype:`wchar_t`.

10569

+Support is optimized if Python's own :c:type:`Py_UNICODE` type is identical to

10570

+the system's :c:type:`wchar_t`.

10571

10572

10573

wchar_t Support

10574

"""""""""""""""

10575

10576

-:ctype:`wchar_t` support for platforms which support it:

10577

+:c:type:`wchar_t` support for platforms which support it:

10578

10579

-.. cfunction:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)

10580

+.. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)

10581

10582

- Create a Unicode object from the :ctype:`wchar_t` buffer *w* of the given *size*.

10583

+ Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*.

10584

Return *NULL* on failure.

10585

10586

.. versionchanged:: 2.5

10587

- This function used an :ctype:`int` type for *size*. This might require

10588

+ This function used an :c:type:`int` type for *size*. This might require

10589

changes in your code for properly supporting 64-bit systems.

10590

10591

10592

-.. cfunction:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)

10593

+.. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)

10594

10595

- Copy the Unicode object contents into the :ctype:`wchar_t` buffer *w*. At most

10596

- *size* :ctype:`wchar_t` characters are copied (excluding a possibly trailing

10597

- 0-termination character). Return the number of :ctype:`wchar_t` characters

10598

- copied or -1 in case of an error. Note that the resulting :ctype:`wchar_t`

10599

+ Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*. At most

10600

+ *size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing

10601

+ 0-termination character). Return the number of :c:type:`wchar_t` characters

10602

+ copied or -1 in case of an error. Note that the resulting :c:type:`wchar_t`

10603

string may or may not be 0-terminated. It is the responsibility of the caller

10604

- to make sure that the :ctype:`wchar_t` string is 0-terminated in case this is

10605

- required by the application.

10606

+ to make sure that the :c:type:`wchar_t` string is 0-terminated in case this is

10607

+ required by the application. Also, note that the :c:type:`wchar_t*` string

10608

+ might contain null characters, which would cause the string to be truncated

10609

+ when used with most C functions.

10610

10611

.. versionchanged:: 2.5

10612

- This function returned an :ctype:`int` type and used an :ctype:`int`

10613

+ This function returned an :c:type:`int` type and used an :c:type:`int`

10614

type for *size*. This might require changes in your code for properly

10615

supporting 64-bit systems.

10616

10617

@@ -412,7 +417,7 @@

10618

object constructor.

10619

10620

Setting encoding to *NULL* causes the default encoding to be used which is

10621

-ASCII. The file system calls should use :cdata:`Py_FileSystemDefaultEncoding`

10622

+ASCII. The file system calls should use :c:data:`Py_FileSystemDefaultEncoding`

10623

as the encoding for file names. This variable should be treated as read-only: on

10624

some systems, it will be a pointer to a static string, on others, it will change

10625

at run-time (such as when the application invokes setlocale).

10626

@@ -431,7 +436,7 @@

10627

These are the generic codec APIs:

10628

10629

10630

-.. cfunction:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)

10631

+.. c:function:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)

10632

10633

Create a Unicode object by decoding *size* bytes of the encoded string *s*.

10634

*encoding* and *errors* have the same meaning as the parameters of the same name

10635

@@ -440,24 +445,24 @@

10636

the codec.

10637

10638

.. versionchanged:: 2.5

10639

- This function used an :ctype:`int` type for *size*. This might require

10640

+ This function used an :c:type:`int` type for *size*. This might require

10641

changes in your code for properly supporting 64-bit systems.

10642

10643

10644

-.. cfunction:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)

10645

+.. c:function:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)

10646

10647

- Encode the :ctype:`Py_UNICODE` buffer *s* of the given *size* and return a Python

10648

+ Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a Python

10649

string object. *encoding* and *errors* have the same meaning as the parameters

10650

of the same name in the Unicode :meth:`encode` method. The codec to be used is

10651

looked up using the Python codec registry. Return *NULL* if an exception was

10652

raised by the codec.

10653

10654

.. versionchanged:: 2.5

10655

- This function used an :ctype:`int` type for *size*. This might require

10656

+ This function used an :c:type:`int` type for *size*. This might require

10657

changes in your code for properly supporting 64-bit systems.

10658

10659

10660

-.. cfunction:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)

10661

+.. c:function:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)

10662

10663

Encode a Unicode object and return the result as Python string object.

10664

*encoding* and *errors* have the same meaning as the parameters of the same name

10665

@@ -472,19 +477,19 @@

10666

These are the UTF-8 codec APIs:

10667

10668

10669

-.. cfunction:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)

10670

+.. c:function:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)

10671

10672

Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string

10673

*s*. Return *NULL* if an exception was raised by the codec.

10674

10675

.. versionchanged:: 2.5

10676

- This function used an :ctype:`int` type for *size*. This might require

10677

+ This function used an :c:type:`int` type for *size*. This might require

10678

changes in your code for properly supporting 64-bit systems.

10679

10680

10681

-.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

10682

+.. c:function:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

10683

10684

- If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF8`. If

10685

+ If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF8`. If

10686

*consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not be

10687

treated as an error. Those bytes will not be decoded and the number of bytes

10688

that have been decoded will be stored in *consumed*.

10689

@@ -492,21 +497,21 @@

10690

.. versionadded:: 2.4

10691

10692

.. versionchanged:: 2.5

10693

- This function used an :ctype:`int` type for *size*. This might require

10694

+ This function used an :c:type:`int` type for *size*. This might require

10695

changes in your code for properly supporting 64-bit systems.

10696

10697

10698

-.. cfunction:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

10699

+.. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

10700

10701

- Encode the :ctype:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 and return a

10702

+ Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 and return a

10703

Python string object. Return *NULL* if an exception was raised by the codec.

10704

10705

.. versionchanged:: 2.5

10706

- This function used an :ctype:`int` type for *size*. This might require

10707

+ This function used an :c:type:`int` type for *size*. This might require

10708

changes in your code for properly supporting 64-bit systems.

10709

10710

10711

-.. cfunction:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)

10712

+.. c:function:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)

10713

10714

Encode a Unicode object using UTF-8 and return the result as Python string

10715

object. Error handling is "strict". Return *NULL* if an exception was raised

10716

@@ -519,7 +524,7 @@

10717

These are the UTF-32 codec APIs:

10718

10719

10720

-.. cfunction:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

10721

+.. c:function:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

10722

10723

Decode *size* bytes from a UTF-32 encoded buffer string and return the

10724

corresponding Unicode object. *errors* (if non-*NULL*) defines the error

10725

@@ -549,10 +554,10 @@

10726

.. versionadded:: 2.6

10727

10728

10729

-.. cfunction:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

10730

+.. c:function:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

10731

10732

- If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF32`. If

10733

- *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF32Stateful` will not treat

10734

+ If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF32`. If

10735

+ *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF32Stateful` will not treat

10736

trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible

10737

by four) as an error. Those bytes will not be decoded and the number of bytes

10738

that have been decoded will be stored in *consumed*.

10739

@@ -560,7 +565,7 @@

10740

.. versionadded:: 2.6

10741

10742

10743

-.. cfunction:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

10744

+.. c:function:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

10745

10746

Return a Python bytes object holding the UTF-32 encoded value of the Unicode

10747

data in *s*. Output is written according to the following byte order::

10748

@@ -580,7 +585,7 @@

10749

.. versionadded:: 2.6

10750

10751

10752

-.. cfunction:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)

10753

+.. c:function:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)

10754

10755

Return a Python string using the UTF-32 encoding in native byte order. The

10756

string always starts with a BOM mark. Error handling is "strict". Return

10757

@@ -595,7 +600,7 @@

10758

These are the UTF-16 codec APIs:

10759

10760

10761

-.. cfunction:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

10762

+.. c:function:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

10763

10764

Decode *size* bytes from a UTF-16 encoded buffer string and return the

10765

corresponding Unicode object. *errors* (if non-*NULL*) defines the error

10766

@@ -622,14 +627,14 @@

10767

Return *NULL* if an exception was raised by the codec.

10768

10769

.. versionchanged:: 2.5

10770

- This function used an :ctype:`int` type for *size*. This might require

10771

+ This function used an :c:type:`int` type for *size*. This might require

10772

changes in your code for properly supporting 64-bit systems.

10773

10774

10775

-.. cfunction:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

10776

+.. c:function:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

10777

10778

- If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF16`. If

10779

- *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF16Stateful` will not treat

10780

+ If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF16`. If

10781

+ *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF16Stateful` will not treat

10782

trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a

10783

split surrogate pair) as an error. Those bytes will not be decoded and the

10784

number of bytes that have been decoded will be stored in *consumed*.

10785

@@ -637,12 +642,12 @@

10786

.. versionadded:: 2.4

10787

10788

.. versionchanged:: 2.5

10789

- This function used an :ctype:`int` type for *size* and an :ctype:`int *`

10790

+ This function used an :c:type:`int` type for *size* and an :c:type:`int *`

10791

type for *consumed*. This might require changes in your code for

10792

properly supporting 64-bit systems.

10793

10794

10795

-.. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

10796

+.. c:function:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

10797

10798

Return a Python string object holding the UTF-16 encoded value of the Unicode

10799

data in *s*. Output is written according to the following byte order::

10800

@@ -654,18 +659,18 @@

10801

If byteorder is ``0``, the output string will always start with the Unicode BOM

10802

mark (U+FEFF). In the other two modes, no BOM mark is prepended.

10803

10804

- If *Py_UNICODE_WIDE* is defined, a single :ctype:`Py_UNICODE` value may get

10805

- represented as a surrogate pair. If it is not defined, each :ctype:`Py_UNICODE`

10806

+ If *Py_UNICODE_WIDE* is defined, a single :c:type:`Py_UNICODE` value may get

10807

+ represented as a surrogate pair. If it is not defined, each :c:type:`Py_UNICODE`

10808

values is interpreted as an UCS-2 character.

10809

10810

Return *NULL* if an exception was raised by the codec.

10811

10812

.. versionchanged:: 2.5

10813

- This function used an :ctype:`int` type for *size*. This might require

10814

+ This function used an :c:type:`int` type for *size*. This might require

10815

changes in your code for properly supporting 64-bit systems.

10816

10817

10818

-.. cfunction:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)

10819

+.. c:function:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)

10820

10821

Return a Python string using the UTF-16 encoding in native byte order. The

10822

string always starts with a BOM mark. Error handling is "strict". Return

10823

@@ -678,23 +683,23 @@

10824

These are the UTF-7 codec APIs:

10825

10826

10827

-.. cfunction:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)

10828

+.. c:function:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)

10829

10830

Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string

10831

*s*. Return *NULL* if an exception was raised by the codec.

10832

10833

10834

-.. cfunction:: PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

10835

+.. c:function:: PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

10836

10837

- If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF7`. If

10838

+ If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF7`. If

10839

*consumed* is not *NULL*, trailing incomplete UTF-7 base-64 sections will not

10840

be treated as an error. Those bytes will not be decoded and the number of

10841

bytes that have been decoded will be stored in *consumed*.

10842

10843

10844

-.. cfunction:: PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)

10845

+.. c:function:: PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)

10846

10847

- Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-7 and

10848

+ Encode the :c:type:`Py_UNICODE` buffer of the given size using UTF-7 and

10849

return a Python bytes object. Return *NULL* if an exception was raised by

10850

the codec.

10851

10852

@@ -710,28 +715,28 @@

10853

These are the "Unicode Escape" codec APIs:

10854

10855

10856

-.. cfunction:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)

10857

+.. c:function:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)

10858

10859

Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded

10860

string *s*. Return *NULL* if an exception was raised by the codec.

10861

10862

.. versionchanged:: 2.5

10863

- This function used an :ctype:`int` type for *size*. This might require

10864

+ This function used an :c:type:`int` type for *size*. This might require

10865

changes in your code for properly supporting 64-bit systems.

10866

10867

10868

-.. cfunction:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)

10869

+.. c:function:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)

10870

10871

- Encode the :ctype:`Py_UNICODE` buffer of the given *size* using Unicode-Escape and

10872

+ Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Unicode-Escape and

10873

return a Python string object. Return *NULL* if an exception was raised by the

10874

codec.

10875

10876

.. versionchanged:: 2.5

10877

- This function used an :ctype:`int` type for *size*. This might require

10878

+ This function used an :c:type:`int` type for *size*. This might require

10879

changes in your code for properly supporting 64-bit systems.

10880

10881

10882

-.. cfunction:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

10883

+.. c:function:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

10884

10885

Encode a Unicode object using Unicode-Escape and return the result as Python

10886

string object. Error handling is "strict". Return *NULL* if an exception was

10887

@@ -744,28 +749,28 @@

10888

These are the "Raw Unicode Escape" codec APIs:

10889

10890

10891

-.. cfunction:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)

10892

+.. c:function:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)

10893

10894

Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape

10895

encoded string *s*. Return *NULL* if an exception was raised by the codec.

10896

10897

.. versionchanged:: 2.5

10898

- This function used an :ctype:`int` type for *size*. This might require

10899

+ This function used an :c:type:`int` type for *size*. This might require

10900

changes in your code for properly supporting 64-bit systems.

10901

10902

10903

-.. cfunction:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

10904

+.. c:function:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

10905

10906

- Encode the :ctype:`Py_UNICODE` buffer of the given *size* using Raw-Unicode-Escape

10907

+ Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Raw-Unicode-Escape

10908

and return a Python string object. Return *NULL* if an exception was raised by

10909

the codec.

10910

10911

.. versionchanged:: 2.5

10912

- This function used an :ctype:`int` type for *size*. This might require

10913

+ This function used an :c:type:`int` type for *size*. This might require

10914

changes in your code for properly supporting 64-bit systems.

10915

10916

10917

-.. cfunction:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

10918

+.. c:function:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

10919

10920

Encode a Unicode object using Raw-Unicode-Escape and return the result as

10921

Python string object. Error handling is "strict". Return *NULL* if an exception

10922

@@ -779,27 +784,27 @@

10923

ordinals and only these are accepted by the codecs during encoding.

10924

10925

10926

-.. cfunction:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)

10927

+.. c:function:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)

10928

10929

Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string

10930

*s*. Return *NULL* if an exception was raised by the codec.

10931

10932

.. versionchanged:: 2.5

10933

- This function used an :ctype:`int` type for *size*. This might require

10934

+ This function used an :c:type:`int` type for *size*. This might require

10935

changes in your code for properly supporting 64-bit systems.

10936

10937

10938

-.. cfunction:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

10939

+.. c:function:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

10940

10941

- Encode the :ctype:`Py_UNICODE` buffer of the given *size* using Latin-1 and return

10942

+ Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Latin-1 and return

10943

a Python string object. Return *NULL* if an exception was raised by the codec.

10944

10945

.. versionchanged:: 2.5

10946

- This function used an :ctype:`int` type for *size*. This might require

10947

+ This function used an :c:type:`int` type for *size*. This might require

10948

changes in your code for properly supporting 64-bit systems.

10949

10950

10951

-.. cfunction:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)

10952

+.. c:function:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)

10953

10954

Encode a Unicode object using Latin-1 and return the result as Python string

10955

object. Error handling is "strict". Return *NULL* if an exception was raised

10956

@@ -813,27 +818,27 @@

10957

codes generate errors.

10958

10959

10960

-.. cfunction:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)

10961

+.. c:function:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)

10962

10963

Create a Unicode object by decoding *size* bytes of the ASCII encoded string

10964

*s*. Return *NULL* if an exception was raised by the codec.

10965

10966

.. versionchanged:: 2.5

10967

- This function used an :ctype:`int` type for *size*. This might require

10968

+ This function used an :c:type:`int` type for *size*. This might require

10969

changes in your code for properly supporting 64-bit systems.

10970

10971

10972

-.. cfunction:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

10973

+.. c:function:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

10974

10975

- Encode the :ctype:`Py_UNICODE` buffer of the given *size* using ASCII and return a

10976

+ Encode the :c:type:`Py_UNICODE` buffer of the given *size* using ASCII and return a

10977

Python string object. Return *NULL* if an exception was raised by the codec.

10978

10979

.. versionchanged:: 2.5

10980

- This function used an :ctype:`int` type for *size*. This might require

10981

+ This function used an :c:type:`int` type for *size*. This might require

10982

changes in your code for properly supporting 64-bit systems.

10983

10984

10985

-.. cfunction:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)

10986

+.. c:function:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)

10987

10988

Encode a Unicode object using ASCII and return the result as Python string

10989

object. Error handling is "strict". Return *NULL* if an exception was raised

10990

@@ -866,7 +871,7 @@

10991

10992

These are the mapping codec APIs:

10993

10994

-.. cfunction:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)

10995

+.. c:function:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)

10996

10997

Create a Unicode object by decoding *size* bytes of the encoded string *s* using

10998

the given *mapping* object. Return *NULL* if an exception was raised by the

10999

@@ -879,22 +884,22 @@

11000

Allowed unicode string as mapping argument.

11001

11002

.. versionchanged:: 2.5

11003

- This function used an :ctype:`int` type for *size*. This might require

11004

+ This function used an :c:type:`int` type for *size*. This might require

11005

changes in your code for properly supporting 64-bit systems.

11006

11007

11008

-.. cfunction:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)

11009

+.. c:function:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)

11010

11011

- Encode the :ctype:`Py_UNICODE` buffer of the given *size* using the given

11012

+ Encode the :c:type:`Py_UNICODE` buffer of the given *size* using the given

11013

*mapping* object and return a Python string object. Return *NULL* if an

11014

exception was raised by the codec.

11015

11016

.. versionchanged:: 2.5

11017

- This function used an :ctype:`int` type for *size*. This might require

11018

+ This function used an :c:type:`int` type for *size*. This might require

11019

changes in your code for properly supporting 64-bit systems.

11020

11021

11022

-.. cfunction:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)

11023

+.. c:function:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)

11024

11025

Encode a Unicode object using the given *mapping* object and return the result

11026

as Python string object. Error handling is "strict". Return *NULL* if an

11027

@@ -903,9 +908,9 @@

11028

The following codec API is special in that maps Unicode to Unicode.

11029

11030

11031

-.. cfunction:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)

11032

+.. c:function:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)

11033

11034

- Translate a :ctype:`Py_UNICODE` buffer of the given *size* by applying a

11035

+ Translate a :c:type:`Py_UNICODE` buffer of the given *size* by applying a

11036

character mapping *table* to it and return the resulting Unicode object. Return

11037

*NULL* when an exception was raised by the codec.

11038

11039

@@ -917,7 +922,7 @@

11040

:exc:`LookupError`) are left untouched and are copied as-is.

11041

11042

.. versionchanged:: 2.5

11043

- This function used an :ctype:`int` type for *size*. This might require

11044

+ This function used an :c:type:`int` type for *size*. This might require

11045

changes in your code for properly supporting 64-bit systems.

11046

11047

11048

@@ -930,37 +935,37 @@

11049

the user settings on the machine running the codec.

11050

11051

11052

-.. cfunction:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)

11053

+.. c:function:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)

11054

11055

Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*.

11056

Return *NULL* if an exception was raised by the codec.

11057

11058

.. versionchanged:: 2.5

11059

- This function used an :ctype:`int` type for *size*. This might require

11060

+ This function used an :c:type:`int` type for *size*. This might require

11061

changes in your code for properly supporting 64-bit systems.

11062

11063

11064

-.. cfunction:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)

11065

+.. c:function:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)

11066

11067

- If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeMBCS`. If

11068

- *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeMBCSStateful` will not decode

11069

+ If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeMBCS`. If

11070

+ *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeMBCSStateful` will not decode

11071

trailing lead byte and the number of bytes that have been decoded will be stored

11072

in *consumed*.

11073

11074

.. versionadded:: 2.5

11075

11076

11077

-.. cfunction:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

11078

+.. c:function:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

11079

11080

- Encode the :ctype:`Py_UNICODE` buffer of the given *size* using MBCS and return a

11081

+ Encode the :c:type:`Py_UNICODE` buffer of the given *size* using MBCS and return a

11082

Python string object. Return *NULL* if an exception was raised by the codec.

11083

11084

.. versionchanged:: 2.5

11085

- This function used an :ctype:`int` type for *size*. This might require

11086

+ This function used an :c:type:`int` type for *size*. This might require

11087

changes in your code for properly supporting 64-bit systems.

11088

11089

11090

-.. cfunction:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)

11091

+.. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)

11092

11093

Encode a Unicode object using MBCS and return the result as Python string

11094

object. Error handling is "strict". Return *NULL* if an exception was raised

11095

@@ -982,12 +987,12 @@

11096

They all return *NULL* or ``-1`` if an exception occurs.

11097

11098

11099

-.. cfunction:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)

11100

+.. c:function:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)

11101

11102

Concat two strings giving a new Unicode string.

11103

11104

11105

-.. cfunction:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)

11106

+.. c:function:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)

11107

11108

Split a string giving a list of Unicode strings. If *sep* is *NULL*, splitting

11109

will be done at all whitespace substrings. Otherwise, splits occur at the given

11110

@@ -995,18 +1000,18 @@

11111

set. Separators are not included in the resulting list.

11112

11113

.. versionchanged:: 2.5

11114

- This function used an :ctype:`int` type for *maxsplit*. This might require

11115

+ This function used an :c:type:`int` type for *maxsplit*. This might require

11116

changes in your code for properly supporting 64-bit systems.

11117

11118

11119

-.. cfunction:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)

11120

+.. c:function:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)

11121

11122

Split a Unicode string at line breaks, returning a list of Unicode strings.

11123

CRLF is considered to be one line break. If *keepend* is 0, the Line break

11124

characters are not included in the resulting strings.

11125

11126

11127

-.. cfunction:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)

11128

+.. c:function:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)

11129

11130

Translate a string by applying a character mapping table to it and return the

11131

resulting Unicode object.

11132

@@ -1022,25 +1027,25 @@

11133

use the default error handling.

11134

11135

11136

-.. cfunction:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)

11137

+.. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)

11138

11139

Join a sequence of strings using the given *separator* and return the resulting

11140

Unicode string.

11141

11142

11143

-.. cfunction:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

11144

+.. c:function:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

11145

11146

Return 1 if *substr* matches ``str[start:end]`` at the given tail end

11147

(*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match),

11148

0 otherwise. Return ``-1`` if an error occurred.

11149

11150

.. versionchanged:: 2.5

11151

- This function used an :ctype:`int` type for *start* and *end*. This

11152

+ This function used an :c:type:`int` type for *start* and *end*. This

11153

might require changes in your code for properly supporting 64-bit

11154

systems.

11155

11156

11157

-.. cfunction:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

11158

+.. c:function:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

11159

11160

Return the first position of *substr* in ``str[start:end]`` using the given

11161

*direction* (*direction* == 1 means to do a forward search, *direction* == -1 a

11162

@@ -1049,40 +1054,40 @@

11163

occurred and an exception has been set.

11164

11165

.. versionchanged:: 2.5

11166

- This function used an :ctype:`int` type for *start* and *end*. This

11167

+ This function used an :c:type:`int` type for *start* and *end*. This

11168

might require changes in your code for properly supporting 64-bit

11169

systems.

11170

11171

11172

-.. cfunction:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)

11173

+.. c:function:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)

11174

11175

Return the number of non-overlapping occurrences of *substr* in

11176

``str[start:end]``. Return ``-1`` if an error occurred.

11177

11178

.. versionchanged:: 2.5

11179

- This function returned an :ctype:`int` type and used an :ctype:`int`

11180

+ This function returned an :c:type:`int` type and used an :c:type:`int`

11181

type for *start* and *end*. This might require changes in your code for

11182

properly supporting 64-bit systems.

11183

11184

11185

-.. cfunction:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)

11186

+.. c:function:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)

11187

11188

Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and

11189

return the resulting Unicode object. *maxcount* == -1 means replace all

11190

occurrences.

11191

11192

.. versionchanged:: 2.5

11193

- This function used an :ctype:`int` type for *maxcount*. This might

11194

+ This function used an :c:type:`int` type for *maxcount*. This might

11195

require changes in your code for properly supporting 64-bit systems.

11196

11197

11198

-.. cfunction:: int PyUnicode_Compare(PyObject *left, PyObject *right)

11199

+.. c:function:: int PyUnicode_Compare(PyObject *left, PyObject *right)

11200

11201

Compare two strings and return -1, 0, 1 for less than, equal, and greater than,

11202

respectively.

11203

11204

11205

-.. cfunction:: int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)

11206

+.. c:function:: int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)

11207

11208

Rich compare two unicode strings and return one of the following:

11209

11210

@@ -1098,13 +1103,13 @@

11211

:const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`.

11212

11213

11214

-.. cfunction:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)

11215

+.. c:function:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)

11216

11217

Return a new string object from *format* and *args*; this is analogous to

11218

``format % args``. The *args* argument must be a tuple.

11219

11220

11221

-.. cfunction:: int PyUnicode_Contains(PyObject *container, PyObject *element)

11222

+.. c:function:: int PyUnicode_Contains(PyObject *container, PyObject *element)

11223

11224

Check whether *element* is contained in *container* and return true or false

11225

accordingly.

11226

diff -r 8527427914a2 Doc/c-api/veryhigh.rst

11227

--- a/Doc/c-api/veryhigh.rst

11228

+++ b/Doc/c-api/veryhigh.rst

11229

@@ -16,23 +16,23 @@

11230

:const:`Py_file_input`, and :const:`Py_single_input`. These are described

11231

following the functions which accept them as parameters.

11232

11233

-Note also that several of these functions take :ctype:`FILE\*` parameters. One

11234

-particular issue which needs to be handled carefully is that the :ctype:`FILE`

11235

+Note also that several of these functions take :c:type:`FILE\*` parameters. One

11236

+particular issue which needs to be handled carefully is that the :c:type:`FILE`

11237

structure for different C libraries can be different and incompatible. Under

11238

Windows (at least), it is possible for dynamically linked extensions to actually

11239

-use different libraries, so care should be taken that :ctype:`FILE\*` parameters

11240

+use different libraries, so care should be taken that :c:type:`FILE\*` parameters

11241

are only passed to these functions if it is certain that they were created by

11242

the same library that the Python runtime is using.

11243

11244

11245

-.. cfunction:: int Py_Main(int argc, char **argv)

11246

+.. c:function:: int Py_Main(int argc, char **argv)

11247

11248

The main program for the standard interpreter. This is made available for

11249

programs which embed Python. The *argc* and *argv* parameters should be

11250

- prepared exactly as those which are passed to a C program's :cfunc:`main`

11251

+ prepared exactly as those which are passed to a C program's :c:func:`main`

11252

function. It is important to note that the argument list may be modified (but

11253

the contents of the strings pointed to by the argument list are not). The return

11254

- value will be ```0``` if the interpreter exits normally (ie, without an

11255

+ value will be ``0`` if the interpreter exits normally (ie, without an

11256

exception), ``1`` if the interpreter exits due to an exception, or ``2``

11257

if the parameter list does not represent a valid Python command line.

11258

11259

@@ -41,40 +41,40 @@

11260

``Py_InspectFlag`` is not set.

11261

11262

11263

-.. cfunction:: int PyRun_AnyFile(FILE *fp, const char *filename)

11264

+.. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename)

11265

11266

- This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving

11267

+ This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving

11268

*closeit* set to ``0`` and *flags* set to *NULL*.

11269

11270

11271

-.. cfunction:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

11272

+.. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

11273

11274

- This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving

11275

+ This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving

11276

the *closeit* argument set to ``0``.

11277

11278

11279

-.. cfunction:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)

11280

+.. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)

11281

11282

- This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving

11283

+ This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving

11284

the *flags* argument set to *NULL*.

11285

11286

11287

-.. cfunction:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

11288

+.. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

11289

11290

If *fp* refers to a file associated with an interactive device (console or

11291

terminal input or Unix pseudo-terminal), return the value of

11292

- :cfunc:`PyRun_InteractiveLoop`, otherwise return the result of

11293

- :cfunc:`PyRun_SimpleFile`. If *filename* is *NULL*, this function uses

11294

+ :c:func:`PyRun_InteractiveLoop`, otherwise return the result of

11295

+ :c:func:`PyRun_SimpleFile`. If *filename* is *NULL*, this function uses

11296

``"???"`` as the filename.

11297

11298

11299

-.. cfunction:: int PyRun_SimpleString(const char *command)

11300

+.. c:function:: int PyRun_SimpleString(const char *command)

11301

11302

- This is a simplified interface to :cfunc:`PyRun_SimpleStringFlags` below,

11303

+ This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below,

11304

leaving the *PyCompilerFlags\** argument set to NULL.

11305

11306

11307

-.. cfunction:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

11308

+.. c:function:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

11309

11310

Executes the Python source code from *command* in the :mod:`__main__` module

11311

according to the *flags* argument. If :mod:`__main__` does not already exist, it

11312

@@ -87,39 +87,39 @@

11313

``Py_InspectFlag`` is not set.

11314

11315

11316

-.. cfunction:: int PyRun_SimpleFile(FILE *fp, const char *filename)

11317

+.. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename)

11318

11319

- This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,

11320

+ This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,

11321

leaving *closeit* set to ``0`` and *flags* set to *NULL*.

11322

11323

11324

-.. cfunction:: int PyRun_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

11325

+.. c:function:: int PyRun_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

11326

11327

- This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,

11328

+ This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,

11329

leaving *closeit* set to ``0``.

11330

11331

11332

-.. cfunction:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)

11333

+.. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)

11334

11335

- This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,

11336

+ This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,

11337

leaving *flags* set to *NULL*.

11338

11339

11340

-.. cfunction:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

11341

+.. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

11342

11343

- Similar to :cfunc:`PyRun_SimpleStringFlags`, but the Python source code is read

11344

+ Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read

11345

from *fp* instead of an in-memory string. *filename* should be the name of the

11346

file. If *closeit* is true, the file is closed before PyRun_SimpleFileExFlags

11347

returns.

11348

11349

11350

-.. cfunction:: int PyRun_InteractiveOne(FILE *fp, const char *filename)

11351

+.. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename)

11352

11353

- This is a simplified interface to :cfunc:`PyRun_InteractiveOneFlags` below,

11354

+ This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below,

11355

leaving *flags* set to *NULL*.

11356

11357

11358

-.. cfunction:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

11359

+.. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

11360

11361

Read and execute a single statement from a file associated with an

11362

interactive device according to the *flags* argument. The user will be

11363

@@ -130,34 +130,34 @@

11364

:file:`Python.h`, so must be included specifically if needed.)

11365

11366

11367

-.. cfunction:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)

11368

+.. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)

11369

11370

- This is a simplified interface to :cfunc:`PyRun_InteractiveLoopFlags` below,

11371

+ This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below,

11372

leaving *flags* set to *NULL*.

11373

11374

11375

-.. cfunction:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

11376

+.. c:function:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

11377

11378

Read and execute statements from a file associated with an interactive device

11379

until EOF is reached. The user will be prompted using ``sys.ps1`` and

11380

``sys.ps2``. Returns ``0`` at EOF.

11381

11382

11383

-.. cfunction:: struct _node* PyParser_SimpleParseString(const char *str, int start)

11384

+.. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start)

11385

11386

This is a simplified interface to

11387

- :cfunc:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set

11388

+ :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set

11389

to *NULL* and *flags* set to ``0``.

11390

11391

11392

-.. cfunction:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)

11393

+.. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)

11394

11395

This is a simplified interface to

11396

- :cfunc:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set

11397

+ :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set

11398

to *NULL*.

11399

11400

11401

-.. cfunction:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)

11402

+.. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)

11403

11404

Parse Python source code from *str* using the start token *start* according to

11405

the *flags* argument. The result can be used to create a code object which can

11406

@@ -165,25 +165,25 @@

11407

many times.

11408

11409

11410

-.. cfunction:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)

11411

+.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)

11412

11413

- This is a simplified interface to :cfunc:`PyParser_SimpleParseFileFlags` below,

11414

+ This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below,

11415

leaving *flags* set to ``0``

11416

11417

11418

-.. cfunction:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)

11419

+.. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)

11420

11421

- Similar to :cfunc:`PyParser_SimpleParseStringFlagsFilename`, but the Python

11422

+ Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python

11423

source code is read from *fp* instead of an in-memory string.

11424

11425

11426

-.. cfunction:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)

11427

+.. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)

11428

11429

- This is a simplified interface to :cfunc:`PyRun_StringFlags` below, leaving

11430

+ This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving

11431

*flags* set to *NULL*.

11432

11433

11434

-.. cfunction:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

11435

+.. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

11436

11437

Execute Python source code from *str* in the context specified by the

11438

dictionaries *globals* and *locals* with the compiler flags specified by

11439

@@ -194,39 +194,39 @@

11440

exception was raised.

11441

11442

11443

-.. cfunction:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)

11444

+.. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)

11445

11446

- This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving

11447

+ This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving

11448

*closeit* set to ``0`` and *flags* set to *NULL*.

11449

11450

11451

-.. cfunction:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)

11452

+.. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)

11453

11454

- This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving

11455

+ This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving

11456

*flags* set to *NULL*.

11457

11458

11459

-.. cfunction:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

11460

+.. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

11461

11462

- This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving

11463

+ This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving

11464

*closeit* set to ``0``.

11465

11466

11467

-.. cfunction:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)

11468

+.. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)

11469

11470

- Similar to :cfunc:`PyRun_StringFlags`, but the Python source code is read from

11471

+ Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from

11472

*fp* instead of an in-memory string. *filename* should be the name of the file.

11473

- If *closeit* is true, the file is closed before :cfunc:`PyRun_FileExFlags`

11474

+ If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags`

11475

returns.

11476

11477

11478

-.. cfunction:: PyObject* Py_CompileString(const char *str, const char *filename, int start)

11479

+.. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start)

11480

11481

- This is a simplified interface to :cfunc:`Py_CompileStringFlags` below, leaving

11482

+ This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving

11483

*flags* set to *NULL*.

11484

11485

11486

-.. cfunction:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)

11487

+.. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)

11488

11489

Parse and compile the Python source code in *str*, returning the resulting code

11490

object. The start token is given by *start*; this can be used to constrain the

11491

@@ -237,14 +237,14 @@

11492

be parsed or compiled.

11493

11494

11495

-.. cfunction:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)

11496

+.. c:function:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)

11497

11498

- This is a simplified interface to :cfunc:`PyEval_EvalCodeEx`, with just

11499

+ This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just

11500

the code object, and the dictionaries of global and local variables.

11501

The other arguments are set to *NULL*.

11502

11503

11504

-.. cfunction:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)

11505

+.. c:function:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)

11506

11507

Evaluate a precompiled code object, given a particular environment for its

11508

evaluation. This environment consists of dictionaries of global and local

11509

@@ -252,13 +252,13 @@

11510

cells.

11511

11512

11513

-.. cfunction:: PyObject* PyEval_EvalFrame(PyFrameObject *f)

11514

+.. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f)

11515

11516

Evaluate an execution frame. This is a simplified interface to

11517

PyEval_EvalFrameEx, for backward compatibility.

11518

11519

11520

-.. cfunction:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

11521

+.. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

11522

11523

This is the main, unvarnished function of Python interpretation. It is

11524

literally 2000 lines long. The code object associated with the execution

11525

@@ -268,39 +268,39 @@

11526

:meth:`throw` methods of generator objects.

11527

11528

11529

-.. cfunction:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

11530

+.. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

11531

11532

This function changes the flags of the current evaluation frame, and returns

11533

true on success, false on failure.

11534

11535

11536

-.. cvar:: int Py_eval_input

11537

+.. c:var:: int Py_eval_input

11538

11539

.. index:: single: Py_CompileString()

11540

11541

The start symbol from the Python grammar for isolated expressions; for use with

11542

- :cfunc:`Py_CompileString`.

11543

+ :c:func:`Py_CompileString`.

11544

11545

11546

-.. cvar:: int Py_file_input

11547

+.. c:var:: int Py_file_input

11548

11549

.. index:: single: Py_CompileString()

11550

11551

The start symbol from the Python grammar for sequences of statements as read

11552

- from a file or other source; for use with :cfunc:`Py_CompileString`. This is

11553

+ from a file or other source; for use with :c:func:`Py_CompileString`. This is

11554

the symbol to use when compiling arbitrarily long Python source code.

11555

11556

11557

-.. cvar:: int Py_single_input

11558

+.. c:var:: int Py_single_input

11559

11560

.. index:: single: Py_CompileString()

11561

11562

The start symbol from the Python grammar for a single statement; for use with

11563

- :cfunc:`Py_CompileString`. This is the symbol used for the interactive

11564

+ :c:func:`Py_CompileString`. This is the symbol used for the interactive

11565

interpreter loop.

11566

11567

11568

-.. ctype:: struct PyCompilerFlags

11569

+.. c:type:: struct PyCompilerFlags

11570

11571

This is the structure used to hold compiler flags. In cases where code is only

11572

being compiled, it is passed as ``int flags``, and in cases where code is being

11573

@@ -316,7 +316,7 @@

11574

}

11575

11576

11577

-.. cvar:: int CO_FUTURE_DIVISION

11578

+.. c:var:: int CO_FUTURE_DIVISION

11579

11580

This bit can be set in *flags* to cause division operator ``/`` to be

11581

interpreted as "true division" according to :pep:`238`.

11582

diff -r 8527427914a2 Doc/c-api/weakref.rst

11583

--- a/Doc/c-api/weakref.rst

11584

+++ b/Doc/c-api/weakref.rst

11585

@@ -11,28 +11,28 @@

11586

as much as it can.

11587

11588

11589

-.. cfunction:: int PyWeakref_Check(ob)

11590

+.. c:function:: int PyWeakref_Check(ob)

11591

11592

Return true if *ob* is either a reference or proxy object.

11593

11594

.. versionadded:: 2.2

11595

11596

11597

-.. cfunction:: int PyWeakref_CheckRef(ob)

11598

+.. c:function:: int PyWeakref_CheckRef(ob)

11599

11600

Return true if *ob* is a reference object.

11601

11602

.. versionadded:: 2.2

11603

11604

11605

-.. cfunction:: int PyWeakref_CheckProxy(ob)

11606

+.. c:function:: int PyWeakref_CheckProxy(ob)

11607

11608

Return true if *ob* is a proxy object.

11609

11610

.. versionadded:: 2.2

11611

11612

11613

-.. cfunction:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)

11614

+.. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)

11615

11616

Return a weak reference object for the object *ob*. This will always return

11617

a new reference, but is not guaranteed to create a new object; an existing

11618

@@ -46,7 +46,7 @@

11619

.. versionadded:: 2.2

11620

11621

11622

-.. cfunction:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)

11623

+.. c:function:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)

11624

11625

Return a weak reference proxy object for the object *ob*. This will always

11626

return a new reference, but is not guaranteed to create a new object; an

11627

@@ -60,7 +60,7 @@

11628

.. versionadded:: 2.2

11629

11630

11631

-.. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref)

11632

+.. c:function:: PyObject* PyWeakref_GetObject(PyObject *ref)

11633

11634

Return the referenced object from a weak reference, *ref*. If the referent is

11635

no longer live, returns :const:`Py_None`.

11636

@@ -70,14 +70,14 @@

11637

.. warning::

11638

11639

This function returns a **borrowed reference** to the referenced object.

11640

- This means that you should always call :cfunc:`Py_INCREF` on the object

11641

+ This means that you should always call :c:func:`Py_INCREF` on the object

11642

except if you know that it cannot be destroyed while you are still

11643

using it.

11644

11645

11646

-.. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)

11647

+.. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)

11648

11649

- Similar to :cfunc:`PyWeakref_GetObject`, but implemented as a macro that does no

11650

+ Similar to :c:func:`PyWeakref_GetObject`, but implemented as a macro that does no

11651

error checking.

11652

11653

.. versionadded:: 2.2

11654

diff -r 8527427914a2 Doc/conf.py

11655

--- a/Doc/conf.py

11656

+++ b/Doc/conf.py

11657

@@ -63,6 +63,9 @@

11658

# Options for HTML output

11659

# -----------------------

11660

11661

+html_theme = 'default'

11662

+html_theme_options = {'collapsiblesidebar': True}

11663

+

11664

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,

11665

# using the given strftime format.

11666

html_last_updated_fmt = '%b %d, %Y'

11667

@@ -83,7 +86,7 @@

11668

}

11669

11670

# Output an OpenSearch description file.

11671

-html_use_opensearch = 'http://docs.python.org/dev'

11672

+html_use_opensearch = 'http://docs.python.org/'

11673

11674

# Additional static files.

11675

html_static_path = ['tools/sphinxext/static']

11676

@@ -112,8 +115,6 @@

11677

'The Python/C API', _stdauthor, 'manual'),

11678

('distutils/index', 'distutils.tex',

11679

'Distributing Python Modules', _stdauthor, 'manual'),

11680

- ('documenting/index', 'documenting.tex',

11681

- 'Documenting Python', 'Georg Brandl', 'manual'),

11682

('extending/index', 'extending.tex',

11683

'Extending and Embedding Python', _stdauthor, 'manual'),

11684

('install/index', 'install.tex',

11685

@@ -151,7 +152,7 @@

11686

latex_appendices = ['glossary', 'about', 'license', 'copyright']

11687

11688

# Get LaTeX to handle Unicode correctly

11689

-latex_elements = {'inputenc': r'\usepackage[utf8x]{inputenc}'}

11690

+latex_elements = {'inputenc': r'\usepackage[utf8x]{inputenc}', 'utf8extra': ''}

11691

11692

# Options for the coverage checker

11693

# --------------------------------

11694

diff -r 8527427914a2 Doc/contents.rst

11695

--- a/Doc/contents.rst

11696

+++ b/Doc/contents.rst

11697

@@ -13,7 +13,6 @@

11698

c-api/index.rst

11699

distutils/index.rst

11700

install/index.rst

11701

- documenting/index.rst

11702

howto/index.rst

11703

faq/index.rst

11704

glossary.rst

11705

diff -r 8527427914a2 Doc/copyright.rst

11706

--- a/Doc/copyright.rst

11707

+++ b/Doc/copyright.rst

11708

@@ -4,7 +4,7 @@

11709

11710

Python and this documentation is:

11711

11712

11713

11714

11715

11716

11717

diff -r 8527427914a2 Doc/distutils/apiref.rst

11718

--- a/Doc/distutils/apiref.rst

11719

+++ b/Doc/distutils/apiref.rst

11720

@@ -31,8 +31,9 @@

11721

+====================+================================+=============================================================+

11722

| *name* | The name of the package | a string |

11723

+--------------------+--------------------------------+-------------------------------------------------------------+

11724

- | *version* | The version number of the | See :mod:`distutils.version` |

11725

- | | package | |

11726

+ | *version* | The version number of the | a string |

11727

+ | | package; see | |

11728

+ | | :mod:`distutils.version` | |

11729

+--------------------+--------------------------------+-------------------------------------------------------------+

11730

| *description* | A single line describing the | a string |

11731

| | package | |

11732

@@ -49,14 +50,14 @@

11733

| | maintainer, if different from | |

11734

| | the author | |

11735

+--------------------+--------------------------------+-------------------------------------------------------------+

11736

- | *maintainer_email* | The email address of the | |

11737

+ | *maintainer_email* | The email address of the | a string |

11738

| | current maintainer, if | |

11739

| | different from the author | |

11740

+--------------------+--------------------------------+-------------------------------------------------------------+

11741

- | *url* | A URL for the package | a URL |

11742

+ | *url* | A URL for the package | a string |

11743

| | (homepage) | |

11744

+--------------------+--------------------------------+-------------------------------------------------------------+

11745

- | *download_url* | A URL to download the package | a URL |

11746

+ | *download_url* | A URL to download the package | a string |

11747

+--------------------+--------------------------------+-------------------------------------------------------------+

11748

| *packages* | A list of Python packages that | a list of strings |

11749

| | distutils will manipulate | |

11750

@@ -68,14 +69,13 @@

11751

| | files to be built and | |

11752

| | installed | |

11753

+--------------------+--------------------------------+-------------------------------------------------------------+

11754

- | *ext_modules* | A list of Python extensions to | A list of instances of |

11755

+ | *ext_modules* | A list of Python extensions to | a list of instances of |

11756

| | be built | :class:`distutils.core.Extension` |

11757

+--------------------+--------------------------------+-------------------------------------------------------------+

11758

- | *classifiers* | A list of categories for the | The list of available |

11759

- | | package | categorizations is at |

11760

- | | | http://pypi.python.org/pypi?:action=list_classifiers. |

11761

+ | *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI |

11762

+ | | package | <http://pypi.python.org/pypi?:action=list_classifiers>`_. |

11763

+--------------------+--------------------------------+-------------------------------------------------------------+

11764

- | *distclass* | the :class:`Distribution` | A subclass of |

11765

+ | *distclass* | the :class:`Distribution` | a subclass of |

11766

| | class to use | :class:`distutils.core.Distribution` |

11767

+--------------------+--------------------------------+-------------------------------------------------------------+

11768

| *script_name* | The name of the setup.py | a string |

11769

@@ -85,15 +85,15 @@

11770

| *script_args* | Arguments to supply to the | a list of strings |

11771

| | setup script | |

11772

+--------------------+--------------------------------+-------------------------------------------------------------+

11773

- | *options* | default options for the setup | a string |

11774

+ | *options* | default options for the setup | a dictionary |

11775

| | script | |

11776

+--------------------+--------------------------------+-------------------------------------------------------------+

11777

| *license* | The license for the package | a string |

11778

+--------------------+--------------------------------+-------------------------------------------------------------+

11779

- | *keywords* | Descriptive meta-data, see | |

11780

+ | *keywords* | Descriptive meta-data, see | a list of strings or a comma-separated string |

11781

| | :pep:`314` | |

11782

+--------------------+--------------------------------+-------------------------------------------------------------+

11783

- | *platforms* | | |

11784

+ | *platforms* | | a list of strings or a comma-separated string |

11785

+--------------------+--------------------------------+-------------------------------------------------------------+

11786

| *cmdclass* | A mapping of command names to | a dictionary |

11787

| | :class:`Command` subclasses | |

11788

@@ -165,13 +165,13 @@

11789

+------------------------+--------------------------------+---------------------------+

11790

| argument name | value | type |

11791

+========================+================================+===========================+

11792

- | *name* | the full name of the | string |

11793

+ | *name* | the full name of the | a string |

11794

| | extension, including any | |

11795

| | packages --- ie. *not* a | |

11796

| | filename or pathname, but | |

11797

| | Python dotted name | |

11798

+------------------------+--------------------------------+---------------------------+

11799

- | *sources* | list of source filenames, | string |

11800

+ | *sources* | list of source filenames, | a list of strings |

11801

| | relative to the distribution | |

11802

| | root (where the setup script | |

11803

| | lives), in Unix form (slash- | |

11804

@@ -184,12 +184,12 @@

11805

| | as source for a Python | |

11806

| | extension. | |

11807

+------------------------+--------------------------------+---------------------------+

11808

- | *include_dirs* | list of directories to search | string |

11809

+ | *include_dirs* | list of directories to search | a list of strings |

11810

| | for C/C++ header files (in | |

11811

| | Unix form for portability) | |

11812

+------------------------+--------------------------------+---------------------------+

11813

- | *define_macros* | list of macros to define; each | (string, string) tuple or |

11814

- | | macro is defined using a | (name, ``None``) |

11815

+ | *define_macros* | list of macros to define; each | a list of tuples |

11816

+ | | macro is defined using a | |

11817

| | 2-tuple ``(name, value)``, | |

11818

| | where *value* is | |

11819

| | either the string to define it | |

11820

@@ -200,31 +200,31 @@

11821

| | on Unix C compiler command | |

11822

| | line) | |

11823

+------------------------+--------------------------------+---------------------------+

11824

- | *undef_macros* | list of macros to undefine | string |

11825

+ | *undef_macros* | list of macros to undefine | a list of strings |

11826

| | explicitly | |

11827

+------------------------+--------------------------------+---------------------------+

11828

- | *library_dirs* | list of directories to search | string |

11829

+ | *library_dirs* | list of directories to search | a list of strings |

11830

| | for C/C++ libraries at link | |

11831

| | time | |

11832

+------------------------+--------------------------------+---------------------------+

11833

- | *libraries* | list of library names (not | string |

11834

+ | *libraries* | list of library names (not | a list of strings |

11835

| | filenames or paths) to link | |

11836

| | against | |

11837

+------------------------+--------------------------------+---------------------------+

11838

- | *runtime_library_dirs* | list of directories to search | string |

11839

+ | *runtime_library_dirs* | list of directories to search | a list of strings |

11840

| | for C/C++ libraries at run | |

11841

| | time (for shared extensions, | |

11842

| | this is when the extension is | |

11843

| | loaded) | |

11844

+------------------------+--------------------------------+---------------------------+

11845

- | *extra_objects* | list of extra files to link | string |

11846

+ | *extra_objects* | list of extra files to link | a list of strings |

11847

| | with (eg. object files not | |

11848

| | implied by 'sources', static | |

11849

| | library that must be | |

11850

| | explicitly specified, binary | |

11851

| | resource files, etc.) | |

11852

+------------------------+--------------------------------+---------------------------+

11853

- | *extra_compile_args* | any extra platform- and | string |

11854

+ | *extra_compile_args* | any extra platform- and | a list of strings |

11855

| | compiler-specific information | |

11856

| | to use when compiling the | |

11857

| | source files in 'sources'. For | |

11858

@@ -235,7 +235,7 @@

11859

| | for other platforms it could | |

11860

| | be anything. | |

11861

+------------------------+--------------------------------+---------------------------+

11862

- | *extra_link_args* | any extra platform- and | string |

11863

+ | *extra_link_args* | any extra platform- and | a list of strings |

11864

| | compiler-specific information | |

11865

| | to use when linking object | |

11866

| | files together to create the | |

11867

@@ -244,7 +244,7 @@

11868

| | Similar interpretation as for | |

11869

| | 'extra_compile_args'. | |

11870

+------------------------+--------------------------------+---------------------------+

11871

- | *export_symbols* | list of symbols to be exported | string |

11872

+ | *export_symbols* | list of symbols to be exported | a list of strings |

11873

| | from a shared extension. Not | |

11874

| | used on all platforms, and not | |

11875

| | generally necessary for Python | |

11876

@@ -252,10 +252,10 @@

11877

| | export exactly one symbol: | |

11878

| | ``init`` + extension_name. | |

11879

+------------------------+--------------------------------+---------------------------+

11880

- | *depends* | list of files that the | string |

11881

+ | *depends* | list of files that the | a list of strings |

11882

| | extension depends on | |

11883

+------------------------+--------------------------------+---------------------------+

11884

- | *language* | extension language (i.e. | string |

11885

+ | *language* | extension language (i.e. | a string |

11886

| | ``'c'``, ``'c++'``, | |

11887

| | ``'objc'``). Will be detected | |

11888

| | from the source extensions if | |

11889

@@ -1736,7 +1736,7 @@

11890

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

11891

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

11892

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

11893

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

11894

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

11895

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

11896

assigned in :meth:`initialize_options`.

11897

11898

@@ -1815,7 +1815,7 @@

11899

.. module:: distutils.command.bdist_msi

11900

:synopsis: Build a binary distribution as a Windows MSI file

11901

11902

-.. class:: bdist_msi(Command)

11903

+.. class:: bdist_msi

11904

11905

Builds a `Windows Installer`_ (.msi) binary package.

11906

11907

diff -r 8527427914a2 Doc/distutils/builtdist.rst

11908

--- a/Doc/distutils/builtdist.rst

11909

+++ b/Doc/distutils/builtdist.rst

11910

@@ -426,7 +426,7 @@

11911

11912

Which folders are available depends on the exact Windows version, and probably

11913

also the configuration. For details refer to Microsoft's documentation of the

11914

- :cfunc:`SHGetSpecialFolderPath` function.

11915

+ :c:func:`SHGetSpecialFolderPath` function.

11916

11917

11918

.. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]])

11919

diff -r 8527427914a2 Doc/distutils/introduction.rst

11920

--- a/Doc/distutils/introduction.rst

11921

+++ b/Doc/distutils/introduction.rst

11922

@@ -79,11 +79,17 @@

11923

for an example)

11924

11925

To create a source distribution for this module, you would create a setup

11926

-script, :file:`setup.py`, containing the above code, and run::

11927

+script, :file:`setup.py`, containing the above code, and run this command from a

11928

+terminal::

11929

11930

python setup.py sdist

11931

11932

-which will create an archive file (e.g., tarball on Unix, ZIP file on Windows)

11933

+For Windows, open a command prompt windows (:menuselection:`Start -->

11934

+Accessories`) and change the command to::

11935

+

11936

+ setup.py sdist

11937

+

11938

+:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows)

11939

containing your setup script :file:`setup.py`, and your module :file:`foo.py`.

11940

The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and

11941

will unpack into a directory :file:`foo-1.0`.

11942

diff -r 8527427914a2 Doc/distutils/setupscript.rst

11943

--- a/Doc/distutils/setupscript.rst

11944

+++ b/Doc/distutils/setupscript.rst

11945

@@ -72,7 +72,7 @@

11946

promising that the Distutils will find a file :file:`foo/__init__.py` (which

11947

might be spelled differently on your system, but you get the idea) relative to

11948

the directory where your setup script lives. If you break this promise, the

11949

-Distutils will issue a warning but still process the broken package anyways.

11950

+Distutils will issue a warning but still process the broken package anyway.

11951

11952

If you use a different convention to lay out your source directory, that's no

11953

problem: you just have to supply the :option:`package_dir` option to tell the

11954

@@ -254,7 +254,7 @@

11955

11956

If you need to include header files from some other Python extension, you can

11957

take advantage of the fact that header files are installed in a consistent way

11958

-by the Distutils :command:`install_header` command. For example, the Numerical

11959

+by the Distutils :command:`install_headers` command. For example, the Numerical

11960

Python header files are installed (on a standard Unix installation) to

11961

:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ

11962

according to your platform and Python installation.) Since the Python include

11963

@@ -334,10 +334,6 @@

11964

11965

There are still some other options which can be used to handle special cases.

11966

11967

-The :option:`optional` option is a boolean; if it is true,

11968

-a build failure in the extension will not abort the build process, but

11969

-instead simply not install the failing extension.

11970

-

11971

The :option:`extra_objects` option is a list of object files to be passed to the

11972

linker. These files must not have extensions, as the default extension for the

11973

compiler is used.

11974

diff -r 8527427914a2 Doc/distutils/sourcedist.rst

11975

--- a/Doc/distutils/sourcedist.rst

11976

+++ b/Doc/distutils/sourcedist.rst

11977

@@ -111,12 +111,22 @@

11978

:file:`MANIFEST`, you must specify everything: the default set of files

11979

described above does not apply in this case.

11980

11981

-.. versionadded:: 2.7

11982

+.. versionchanged:: 2.7

11983

+ An existing generated :file:`MANIFEST` will be regenerated without

11984

+ :command:`sdist` comparing its modification time to the one of

11985

+ :file:`MANIFEST.in` or :file:`setup.py`.

11986

+

11987

+.. versionchanged:: 2.7.1

11988

:file:`MANIFEST` files start with a comment indicating they are generated.

11989

Files without this comment are not overwritten or removed.

11990

11991

+.. versionchanged:: 2.7.3

11992

+ :command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in`

11993

+ exists, like it did before 2.7.

11994

+

11995

See :ref:`manifest_template` section for a syntax reference.

11996

11997

+

11998

.. _manifest-options:

11999

12000

Manifest-related options

12001

@@ -124,16 +134,16 @@

12002

12003

The normal course of operations for the :command:`sdist` command is as follows:

12004

12005

-* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`

12006

- and create the manifest

12007

+* if the manifest file (:file:`MANIFEST` by default) exists and the first line

12008

+ does not have a comment indicating it is generated from :file:`MANIFEST.in`,

12009

+ then it is used as is, unaltered

12010

+

12011

+* if the manifest file doesn't exist or has been previously automatically

12012

+ generated, read :file:`MANIFEST.in` and create the manifest

12013

12014

* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest

12015

with just the default file set

12016

12017

-* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more

12018

- recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading

12019

- :file:`MANIFEST.in`

12020

-

12021

* use the list of files now in :file:`MANIFEST` (either just generated or read

12022

in) to create the source distribution archive(s)

12023

12024

@@ -271,8 +281,3 @@

12025

``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename

12026

character" is platform-specific: on Unix it is anything except slash; on Windows

12027

anything except backslash or colon.

12028

-

12029

-.. versionchanged:: 2.7

12030

- An existing generated :file:`MANIFEST` will be regenerated without

12031

- :command:`sdist` comparing its modification time to the one of

12032

- :file:`MANIFEST.in` or :file:`setup.py`.

12033

diff -r 8527427914a2 Doc/documenting/building.rst

12034

--- a/Doc/documenting/building.rst

12035

+++ /dev/null

12036

@@ -1,91 +0,0 @@

12037

-Building the documentation

12038

-==========================

12039

-

12040

-You need to have Python 2.4 or higher installed; the toolset used to build the

12041

-docs is written in Python. It is called *Sphinx*, it is not included in this

12042

-tree, but maintained separately. Also needed are the docutils, supplying the

12043

-base markup that Sphinx uses, Jinja, a templating engine, and optionally

12044

-Pygments, a code highlighter.

12045

-

12046

-

12047

-Using make

12048

-----------

12049

-

12050

-Luckily, a Makefile has been prepared so that on Unix, provided you have

12051

-installed Python and Subversion, you can just run ::

12052

-

12053

- make html

12054

-

12055

-to check out the necessary toolset in the `tools/` subdirectory and build the

12056

-HTML output files. To view the generated HTML, point your favorite browser at

12057

-the top-level index `build/html/index.html` after running "make".

12058

-

12059

-Available make targets are:

12060

-

12061

- * "html", which builds standalone HTML files for offline viewing.

12062

-

12063

- * "htmlhelp", which builds HTML files and a HTML Help project file usable to

12064

- convert them into a single Compiled HTML (.chm) file -- these are popular

12065

- under Microsoft Windows, but very handy on every platform.

12066

-

12067

- To create the CHM file, you need to run the Microsoft HTML Help Workshop

12068

- over the generated project (.hhp) file.

12069

-

12070

- * "latex", which builds LaTeX source files as input to "pdflatex" to produce

12071

- PDF documents.

12072

-

12073

- * "text", which builds a plain text file for each source file.

12074

-

12075

- * "linkcheck", which checks all external references to see whether they are

12076

- broken, redirected or malformed, and outputs this information to stdout

12077

- as well as a plain-text (.txt) file.

12078

-

12079

- * "changes", which builds an overview over all versionadded/versionchanged/

12080

- deprecated items in the current version. This is meant as a help for the

12081

- writer of the "What's New" document.

12082

-

12083

- * "coverage", which builds a coverage overview for standard library modules

12084

- and C API.

12085

-

12086

- * "pydoc-topics", which builds a Python module containing a dictionary with

12087

- plain text documentation for the labels defined in

12088

- `tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and

12089

- keyword help.

12090

-

12091

-A "make update" updates the Subversion checkouts in `tools/`.

12092

-

12093

-

12094

-Without make

12095

-------------

12096

-

12097

-You'll need to install the Sphinx package, either by checking it out via ::

12098

-

12099

- svn co http://svn.python.org/projects/external/Sphinx-0.6.5/sphinx tools/sphinx

12100

-

12101

-or by installing it from PyPI.

12102

-

12103

-Then, you need to install Docutils, either by checking it out via ::

12104

-

12105

- svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils

12106

-

12107

-or by installing it from http://docutils.sf.net/.

12108

-

12109

-You also need Jinja2, either by checking it out via ::

12110

-

12111

- svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2

12112

-

12113

-or by installing it from PyPI.

12114

-

12115

-You can optionally also install Pygments, either as a checkout via ::

12116

-

12117

- svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments

12118

-

12119

-or from PyPI at http://pypi.python.org/pypi/Pygments.

12120

-

12121

-

12122

-Then, make an output directory, e.g. under `build/`, and run ::

12123

-

12124

- python tools/sphinx-build.py -b<builder> . build/<outputdirectory>

12125

-

12126

-where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see

12127

-the make targets above).

12128

diff -r 8527427914a2 Doc/documenting/fromlatex.rst

12129

--- a/Doc/documenting/fromlatex.rst

12130

+++ /dev/null

12131

@@ -1,202 +0,0 @@

12132

-.. highlightlang:: rest

12133

-

12134

-Differences to the LaTeX markup

12135

-===============================

12136

-

12137

-Though the markup language is different, most of the concepts and markup types

12138

-of the old LaTeX docs have been kept -- environments as reST directives, inline

12139

-commands as reST roles and so forth.

12140

-

12141

-However, there are some differences in the way these work, partly due to the

12142

-differences in the markup languages, partly due to improvements in Sphinx. This

12143

-section lists these differences, in order to give those familiar with the old

12144

-format a quick overview of what they might run into.

12145

-

12146

-Inline markup

12147

--------------

12148

-

12149

-These changes have been made to inline markup:

12150

-

12151

-* **Cross-reference roles**

12152

-

12153

- Most of the following semantic roles existed previously as inline commands,

12154

- but didn't do anything except formatting the content as code. Now, they

12155

- cross-reference to known targets (some names have also been shortened):

12156

-

12157

- | *mod* (previously *refmodule* or *module*)

12158

- | *func* (previously *function*)

12159

- | *data* (new)

12160

- | *const*

12161

- | *class*

12162

- | *meth* (previously *method*)

12163

- | *attr* (previously *member*)

12164

- | *exc* (previously *exception*)

12165

- | *cdata*

12166

- | *cfunc* (previously *cfunction*)

12167

- | *cmacro* (previously *csimplemacro*)

12168

- | *ctype*

12169

-

12170

- Also different is the handling of *func* and *meth*: while previously

12171

- parentheses were added to the callable name (like ``\func{str()}``), they are

12172

- now appended by the build system -- appending them in the source will result

12173

- in double parentheses. This also means that ``:func:`str(object)``` will not

12174

- work as expected -- use ````str(object)```` instead!

12175

-

12176

-* **Inline commands implemented as directives**

12177

-

12178

- These were inline commands in LaTeX, but are now directives in reST:

12179

-

12180

- | *deprecated*

12181

- | *versionadded*

12182

- | *versionchanged*

12183

-

12184

- These are used like so::

12185

-

12186

- .. deprecated:: 2.5

12187

- Reason of deprecation.

12188

-

12189

- Also, no period is appended to the text for *versionadded* and

12190

- *versionchanged*.

12191

-

12192

- | *note*

12193

- | *warning*

12194

-

12195

- These are used like so::

12196

-

12197

- .. note::

12198

-

12199

- Content of note.

12200

-

12201

-* **Otherwise changed commands**

12202

-

12203

- The *samp* command previously formatted code and added quotation marks around

12204

- it. The *samp* role, however, features a new highlighting system just like

12205

- *file* does:

12206

-

12207

- ``:samp:`open({filename}, {mode})``` results in :samp:`open({filename}, {mode})`

12208

-

12209

-* **Dropped commands**

12210

-

12211

- These were commands in LaTeX, but are not available as roles:

12212

-

12213

- | *bfcode*

12214

- | *character* (use :samp:`\`\`'c'\`\``)

12215

- | *citetitle* (use ```Title <URL>`_``)

12216

- | *code* (use ````code````)

12217

- | *email* (just write the address in body text)

12218

- | *filenq*

12219

- | *filevar* (use the ``{...}`` highlighting feature of *file*)

12220

- | *programopt*, *longprogramopt* (use *option*)

12221

- | *ulink* (use ```Title <URL>`_``)

12222

- | *url* (just write the URL in body text)

12223

- | *var* (use ``*var*``)

12224

- | *infinity*, *plusminus* (use the Unicode character)

12225

12226

- | *emph*, *strong* (use the reST markup)

12227

-

12228

-* **Backslash escaping**

12229

-

12230

- In reST, a backslash must be escaped in normal text, and in the content of

12231

- roles. However, in code literals and literal blocks, it must not be escaped.

12232

- Example: ``:file:`C:\\Temp\\my.tmp``` vs. ````open("C:\Temp\my.tmp")````.

12233

-

12234

-

12235

-Information units

12236

------------------

12237

-

12238

-Information units (*...desc* environments) have been made reST directives.

12239

-These changes to information units should be noted:

12240

-

12241

-* **New names**

12242

-

12243

- "desc" has been removed from every name. Additionally, these directives have

12244

- new names:

12245

-

12246

- | *cfunction* (previously *cfuncdesc*)

12247

- | *cmacro* (previously *csimplemacrodesc*)

12248

- | *exception* (previously *excdesc*)

12249

- | *function* (previously *funcdesc*)

12250

- | *attribute* (previously *memberdesc*)

12251

-

12252

- The *classdesc\** and *excclassdesc* environments have been dropped, the

12253

- *class* and *exception* directives support classes documented with and without

12254

- constructor arguments.

12255

-

12256

-* **Multiple objects**

12257

-

12258

- The equivalent of the *...line* commands is::

12259

-

12260

- .. function:: do_foo(bar)

12261

- do_bar(baz)

12262

-

12263

- Description of the functions.

12264

-

12265

- IOW, just give one signatures per line, at the same indentation level.

12266

-

12267

-* **Arguments**

12268

-

12269

- There is no *optional* command. Just give function signatures like they

12270

- should appear in the output::

12271

-

12272

- .. function:: open(filename[, mode[, buffering]])

12273

-

12274

- Description.

12275

-

12276

- Note: markup in the signature is not supported.

12277

-

12278

-* **Indexing**

12279

-

12280

- The *...descni* environments have been dropped. To mark an information unit

12281

- as unsuitable for index entry generation, use the *noindex* option like so::

12282

-

12283

- .. function:: foo_*

12284

- :noindex:

12285

-

12286

- Description.

12287

-

12288

-* **New information units**

12289

-

12290

- There are new generic information units: One is called "describe" and can be

12291

- used to document things that are not covered by the other units::

12292

-

12293

- .. describe:: a == b

12294

-

12295

- The equals operator.

12296

-

12297

- The others are::

12298

-

12299

- .. cmdoption:: -O

12300

-

12301

- Describes a command-line option.

12302

-

12303

- .. envvar:: PYTHONINSPECT

12304

-

12305

- Describes an environment variable.

12306

-

12307

-

12308

-Structure

12309

----------

12310

-

12311

-The LaTeX docs were split in several toplevel manuals. Now, all files are part

12312

-of the same documentation tree, as indicated by the *toctree* directives in the

12313

-sources (though individual output formats may choose to split them up into parts

12314

-again). Every *toctree* directive embeds other files as subdocuments of the

12315

-current file (this structure is not necessarily mirrored in the filesystem

12316

-layout). The toplevel file is :file:`contents.rst`.

12317

-

12318

-However, most of the old directory structure has been kept, with the

12319

-directories renamed as follows:

12320

-

12321

-* :file:`api` -> :file:`c-api`

12322

-* :file:`dist` -> :file:`distutils`, with the single TeX file split up

12323

-* :file:`doc` -> :file:`documenting`

12324

-* :file:`ext` -> :file:`extending`

12325

-* :file:`inst` -> :file:`installing`

12326

-* :file:`lib` -> :file:`library`

12327

-* :file:`mac` -> merged into :file:`library`, with :file:`mac/using.tex`

12328

- moved to :file:`using/mac.rst`

12329

-* :file:`ref` -> :file:`reference`

12330

-* :file:`tut` -> :file:`tutorial`, with the single TeX file split up

12331

-

12332

-

12333

-.. XXX more (index-generating, production lists, ...)

12334

diff -r 8527427914a2 Doc/documenting/index.rst

12335

--- a/Doc/documenting/index.rst

12336

+++ /dev/null

12337

@@ -1,38 +0,0 @@

12338

-.. _documenting-index:

12339

-

12340

-######################

12341

- Documenting Python

12342

-######################

12343

-

12344

-

12345

-The Python language has a substantial body of documentation, much of it

12346

-contributed by various authors. The markup used for the Python documentation is

12347

-`reStructuredText`_, developed by the `docutils`_ project, amended by custom

12348

-directives and using a toolset named `Sphinx`_ to postprocess the HTML output.

12349

-

12350

-This document describes the style guide for our documentation as well as the

12351

-custom reStructuredText markup introduced by Sphinx to support Python

12352

-documentation and how it should be used.

12353

-

12354

-.. _reStructuredText: http://docutils.sf.net/rst.html

12355

-.. _docutils: http://docutils.sf.net/

12356

-.. _Sphinx: http://sphinx.pocoo.org/

12357

-

12358

-.. note::

12359

-

12360

- If you're interested in contributing to Python's documentation, there's no

12361

- need to write reStructuredText if you're not so inclined; plain text

12362

- contributions are more than welcome as well. Send an e-mail to

12363

- docs@python.org or open an issue on the :ref:`tracker <reporting-bugs>`.

12364

-

12365

-

12366

-.. toctree::

12367

- :numbered:

12368

- :maxdepth: 1

12369

-

12370

- intro.rst

12371

- style.rst

12372

- rest.rst

12373

- markup.rst

12374

- fromlatex.rst

12375

- building.rst

12376

diff -r 8527427914a2 Doc/documenting/intro.rst

12377

--- a/Doc/documenting/intro.rst

12378

+++ /dev/null

12379

@@ -1,29 +0,0 @@

12380

-Introduction

12381

-============

12382

-

12383

-Python's documentation has long been considered to be good for a free

12384

-programming language. There are a number of reasons for this, the most

12385

-important being the early commitment of Python's creator, Guido van Rossum, to

12386

-providing documentation on the language and its libraries, and the continuing

12387

-involvement of the user community in providing assistance for creating and

12388

-maintaining documentation.

12389

-

12390

-The involvement of the community takes many forms, from authoring to bug reports

12391

-to just plain complaining when the documentation could be more complete or

12392

-easier to use.

12393

-

12394

-This document is aimed at authors and potential authors of documentation for

12395

-Python. More specifically, it is for people contributing to the standard

12396

-documentation and developing additional documents using the same tools as the

12397

-standard documents. This guide will be less useful for authors using the Python

12398

-documentation tools for topics other than Python, and less useful still for

12399

-authors not using the tools at all.

12400

-

12401

-If your interest is in contributing to the Python documentation, but you don't

12402

-have the time or inclination to learn reStructuredText and the markup structures

12403

-documented here, there's a welcoming place for you among the Python contributors

12404

-as well. Any time you feel that you can clarify existing documentation or

12405

-provide documentation that's missing, the existing documentation team will

12406

-gladly work with you to integrate your text, dealing with the markup for you.

12407

-Please don't let the material in this document stand between the documentation

12408

-and your desire to help out!

12409

\ No newline at end of file

12410

diff -r 8527427914a2 Doc/documenting/markup.rst

12411

--- a/Doc/documenting/markup.rst

12412

+++ /dev/null

12413

@@ -1,857 +0,0 @@

12414

-.. highlightlang:: rest

12415

-

12416

-Additional Markup Constructs

12417

-============================

12418

-

12419

-Sphinx adds a lot of new directives and interpreted text roles to standard reST

12420

-markup. This section contains the reference material for these facilities.

12421

-Documentation for "standard" reST constructs is not included here, though

12422

-they are used in the Python documentation.

12423

-

12424

-.. note::

12425

-

12426

- This is just an overview of Sphinx' extended markup capabilities; full

12427

- coverage can be found in `its own documentation

12428

- <http://sphinx.pocoo.org/contents.html>`_.

12429

-

12430

-

12431

-Meta-information markup

12432

------------------------

12433

-

12434

-.. describe:: sectionauthor

12435

-

12436

- Identifies the author of the current section. The argument should include

12437

- the author's name such that it can be used for presentation (though it isn't)

12438

- and email address. The domain name portion of the address should be lower

12439

- case. Example::

12440

-

12441

- .. sectionauthor:: Guido van Rossum <guido@python.org>

12442

-

12443

- Currently, this markup isn't reflected in the output in any way, but it helps

12444

- keep track of contributions.

12445

-

12446

-

12447

-Module-specific markup

12448

-----------------------

12449

-

12450

-The markup described in this section is used to provide information about a

12451

-module being documented. Each module should be documented in its own file.

12452

-Normally this markup appears after the title heading of that file; a typical

12453

-file might start like this::

12454

-

12455

- :mod:`parrot` -- Dead parrot access

12456

- ===================================

12457

-

12458

- .. module:: parrot

12459

- :platform: Unix, Windows

12460

- :synopsis: Analyze and reanimate dead parrots.

12461

- .. moduleauthor:: Eric Cleese <eric@python.invalid>

12462

- .. moduleauthor:: John Idle <john@python.invalid>

12463

-

12464

-As you can see, the module-specific markup consists of two directives, the

12465

-``module`` directive and the ``moduleauthor`` directive.

12466

-

12467

-.. describe:: module

12468

-

12469

- This directive marks the beginning of the description of a module (or package

12470

- submodule, in which case the name should be fully qualified, including the

12471

- package name).

12472

-

12473

- The ``platform`` option, if present, is a comma-separated list of the

12474

- platforms on which the module is available (if it is available on all

12475

- platforms, the option should be omitted). The keys are short identifiers;

12476

- examples that are in use include "IRIX", "Mac", "Windows", and "Unix". It is

12477

- important to use a key which has already been used when applicable.

12478

-

12479

- The ``synopsis`` option should consist of one sentence describing the

12480

- module's purpose -- it is currently only used in the Global Module Index.

12481

-

12482

- The ``deprecated`` option can be given (with no value) to mark a module as

12483

- deprecated; it will be designated as such in various locations then.

12484

-

12485

-.. describe:: moduleauthor

12486

-

12487

- The ``moduleauthor`` directive, which can appear multiple times, names the

12488

- authors of the module code, just like ``sectionauthor`` names the author(s)

12489

- of a piece of documentation. It too does not result in any output currently.

12490

-

12491

-.. note::

12492

-

12493

- It is important to make the section title of a module-describing file

12494

- meaningful since that value will be inserted in the table-of-contents trees

12495

- in overview files.

12496

-

12497

-

12498

-Information units

12499

------------------

12500

-

12501

-There are a number of directives used to describe specific features provided by

12502

-modules. Each directive requires one or more signatures to provide basic

12503

-information about what is being described, and the content should be the

12504

-description. The basic version makes entries in the general index; if no index

12505

-entry is desired, you can give the directive option flag ``:noindex:``. The

12506

-following example shows all of the features of this directive type::

12507

-

12508

- .. function:: spam(eggs)

12509

- ham(eggs)

12510

- :noindex:

12511

-

12512

- Spam or ham the foo.

12513

-

12514

-The signatures of object methods or data attributes should always include the

12515

-type name (``.. method:: FileInput.input(...)``), even if it is obvious from the

12516

-context which type they belong to; this is to enable consistent

12517

-cross-references. If you describe methods belonging to an abstract protocol,

12518

-such as "context managers", include a (pseudo-)type name too to make the

12519

-index entries more informative.

12520

-

12521

-The directives are:

12522

-

12523

-.. describe:: cfunction

12524

-

12525

- Describes a C function. The signature should be given as in C, e.g.::

12526

-

12527

- .. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

12528

-

12529

- This is also used to describe function-like preprocessor macros. The names

12530

- of the arguments should be given so they may be used in the description.

12531

-

12532

- Note that you don't have to backslash-escape asterisks in the signature,

12533

- as it is not parsed by the reST inliner.

12534

-

12535

-.. describe:: cmember

12536

-

12537

- Describes a C struct member. Example signature::

12538

-

12539

- .. cmember:: PyObject* PyTypeObject.tp_bases

12540

-

12541

- The text of the description should include the range of values allowed, how

12542

- the value should be interpreted, and whether the value can be changed.

12543

- References to structure members in text should use the ``member`` role.

12544

-

12545

-.. describe:: cmacro

12546

-

12547

- Describes a "simple" C macro. Simple macros are macros which are used

12548

- for code expansion, but which do not take arguments so cannot be described as

12549

- functions. This is not to be used for simple constant definitions. Examples

12550

- of its use in the Python documentation include :cmacro:`PyObject_HEAD` and

12551

- :cmacro:`Py_BEGIN_ALLOW_THREADS`.

12552

-

12553

-.. describe:: ctype

12554

-

12555

- Describes a C type. The signature should just be the type name.

12556

-

12557

-.. describe:: cvar

12558

-

12559

- Describes a global C variable. The signature should include the type, such

12560

- as::

12561

-

12562

- .. cvar:: PyObject* PyClass_Type

12563

-

12564

-.. describe:: data

12565

-

12566

- Describes global data in a module, including both variables and values used

12567

- as "defined constants." Class and object attributes are not documented

12568

- using this directive.

12569

-

12570

-.. describe:: exception

12571

-

12572

- Describes an exception class. The signature can, but need not include

12573

- parentheses with constructor arguments.

12574

-

12575

-.. describe:: function

12576

-

12577

- Describes a module-level function. The signature should include the

12578

- parameters, enclosing optional parameters in brackets. Default values can be

12579

- given if it enhances clarity. For example::

12580

-

12581

- .. function:: repeat([repeat=3[, number=1000000]])

12582

-

12583

- Object methods are not documented using this directive. Bound object methods

12584

- placed in the module namespace as part of the public interface of the module

12585

- are documented using this, as they are equivalent to normal functions for

12586

- most purposes.

12587

-

12588

- The description should include information about the parameters required and

12589

- how they are used (especially whether mutable objects passed as parameters

12590

- are modified), side effects, and possible exceptions. A small example may be

12591

- provided.

12592

-

12593

-.. describe:: class

12594

-

12595

- Describes a class. The signature can include parentheses with parameters

12596

- which will be shown as the constructor arguments.

12597

-

12598

-.. describe:: attribute

12599

-

12600

- Describes an object data attribute. The description should include

12601

- information about the type of the data to be expected and whether it may be

12602

- changed directly. This directive should be nested in a class directive,

12603

- like in this example::

12604

-

12605

- .. class:: Spam

12606

-

12607

- Description of the class.

12608

-

12609

- .. data:: ham

12610

-

12611

- Description of the attribute.

12612

-

12613

- If is also possible to document an attribute outside of a class directive,

12614

- for example if the documentation for different attributes and methods is

12615

- split in multiple sections. The class name should then be included

12616

- explicitly::

12617

-

12618

- .. data:: Spam.eggs

12619

-

12620

-.. describe:: method

12621

-

12622

- Describes an object method. The parameters should not include the ``self``

12623

- parameter. The description should include similar information to that

12624

- described for ``function``. This directive should be nested in a class

12625

- directive, like in the example above.

12626

-

12627

-.. describe:: opcode

12628

-

12629

- Describes a Python :term:`bytecode` instruction.

12630

-

12631

-.. describe:: cmdoption

12632

-

12633

- Describes a Python command line option or switch. Option argument names

12634

- should be enclosed in angle brackets. Example::

12635

-

12636

- .. cmdoption:: -m <module>

12637

-

12638

- Run a module as a script.

12639

-

12640

-.. describe:: envvar

12641

-

12642

- Describes an environment variable that Python uses or defines.

12643

-

12644

-

12645

-There is also a generic version of these directives:

12646

-

12647

-.. describe:: describe

12648

-

12649

- This directive produces the same formatting as the specific ones explained

12650

- above but does not create index entries or cross-referencing targets. It is

12651

- used, for example, to describe the directives in this document. Example::

12652

-

12653

- .. describe:: opcode

12654

-

12655

- Describes a Python bytecode instruction.

12656

-

12657

-

12658

-Showing code examples

12659

----------------------

12660

-

12661

-Examples of Python source code or interactive sessions are represented using

12662

-standard reST literal blocks. They are started by a ``::`` at the end of the

12663

-preceding paragraph and delimited by indentation.

12664

-

12665

-Representing an interactive session requires including the prompts and output

12666

-along with the Python code. No special markup is required for interactive

12667

-sessions. After the last line of input or output presented, there should not be

12668

-an "unused" primary prompt; this is an example of what *not* to do::

12669

-

12670

- >>> 1 + 1

12671

- 2

12672

- >>>

12673

-

12674

-Syntax highlighting is handled in a smart way:

12675

-

12676

-* There is a "highlighting language" for each source file. Per default,

12677

- this is ``'python'`` as the majority of files will have to highlight Python

12678

- snippets.

12679

-

12680

-* Within Python highlighting mode, interactive sessions are recognized

12681

- automatically and highlighted appropriately.

12682

-

12683

-* The highlighting language can be changed using the ``highlightlang``

12684

- directive, used as follows::

12685

-

12686

- .. highlightlang:: c

12687

-

12688

- This language is used until the next ``highlightlang`` directive is

12689

- encountered.

12690

-

12691

-* The values normally used for the highlighting language are:

12692

-

12693

- * ``python`` (the default)

12694

- * ``c``

12695

- * ``rest``

12696

- * ``none`` (no highlighting)

12697

-

12698

-* If highlighting with the current language fails, the block is not highlighted

12699

- in any way.

12700

-

12701

-Longer displays of verbatim text may be included by storing the example text in

12702

-an external file containing only plain text. The file may be included using the

12703

-``literalinclude`` directive. [1]_ For example, to include the Python source file

12704

-:file:`example.py`, use::

12705

-

12706

- .. literalinclude:: example.py

12707

-

12708

-The file name is relative to the current file's path. Documentation-specific

12709

-include files should be placed in the ``Doc/includes`` subdirectory.

12710

-

12711

-

12712

-Inline markup

12713

--------------

12714

-

12715

-As said before, Sphinx uses interpreted text roles to insert semantic markup in

12716

-documents.

12717

-

12718

-Names of local variables, such as function/method arguments, are an exception,

12719

-they should be marked simply with ``*var*``.

12720

-

12721

-For all other roles, you have to write ``:rolename:`content```.

12722

-

12723

-There are some additional facilities that make cross-referencing roles more

12724

-versatile:

12725

-

12726

-* You may supply an explicit title and reference target, like in reST direct

12727

- hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link

12728

- text will be *title*.

12729

-

12730

-* If you prefix the content with ``!``, no reference/hyperlink will be created.

12731

-

12732

-* For the Python object roles, if you prefix the content with ``~``, the link

12733

- text will only be the last component of the target. For example,

12734

- ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only

12735

- display ``get`` as the link text.

12736

-

12737

- In HTML output, the link's ``title`` attribute (that is e.g. shown as a

12738

- tool-tip on mouse-hover) will always be the full target name.

12739

-

12740

-The following roles refer to objects in modules and are possibly hyperlinked if

12741

-a matching identifier is found:

12742

-

12743

-.. describe:: mod

12744

-

12745

- The name of a module; a dotted name may be used. This should also be used for

12746

- package names.

12747

-

12748

-.. describe:: func

12749

-

12750

- The name of a Python function; dotted names may be used. The role text

12751

- should not include trailing parentheses to enhance readability. The

12752

- parentheses are stripped when searching for identifiers.

12753

-

12754

-.. describe:: data

12755

-

12756

- The name of a module-level variable or constant.

12757

-

12758

-.. describe:: const

12759

-

12760

- The name of a "defined" constant. This may be a C-language ``#define``

12761

- or a Python variable that is not intended to be changed.

12762

-

12763

-.. describe:: class

12764

-

12765

- A class name; a dotted name may be used.

12766

-

12767

-.. describe:: meth

12768

-

12769

- The name of a method of an object. The role text should include the type

12770

- name and the method name. A dotted name may be used.

12771

-

12772

-.. describe:: attr

12773

-

12774

- The name of a data attribute of an object.

12775

-

12776

-.. describe:: exc

12777

-

12778

- The name of an exception. A dotted name may be used.

12779

-

12780

-The name enclosed in this markup can include a module name and/or a class name.

12781

-For example, ``:func:`filter``` could refer to a function named ``filter`` in

12782

-the current module, or the built-in function of that name. In contrast,

12783

-``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``

12784

-module.

12785

-

12786

-Normally, names in these roles are searched first without any further

12787

-qualification, then with the current module name prepended, then with the

12788

-current module and class name (if any) prepended. If you prefix the name with a

12789

-dot, this order is reversed. For example, in the documentation of the

12790

-:mod:`codecs` module, ``:func:`open``` always refers to the built-in function,

12791

-while ``:func:`.open``` refers to :func:`codecs.open`.

12792

-

12793

-A similar heuristic is used to determine whether the name is an attribute of

12794

-the currently documented class.

12795

-

12796

-The following roles create cross-references to C-language constructs if they

12797

-are defined in the API documentation:

12798

-

12799

-.. describe:: cdata

12800

-

12801

- The name of a C-language variable.

12802

-

12803

-.. describe:: cfunc

12804

-

12805

- The name of a C-language function. Should include trailing parentheses.

12806

-

12807

-.. describe:: cmacro

12808

-

12809

- The name of a "simple" C macro, as defined above.

12810

-

12811

-.. describe:: ctype

12812

-

12813

- The name of a C-language type.

12814

-

12815

-

12816

-The following role does possibly create a cross-reference, but does not refer

12817

-to objects:

12818

-

12819

-.. describe:: token

12820

-

12821

- The name of a grammar token (used in the reference manual to create links

12822

- between production displays).

12823

-

12824

-

12825

-The following role creates a cross-reference to the term in the glossary:

12826

-

12827

-.. describe:: term

12828

-

12829

- Reference to a term in the glossary. The glossary is created using the

12830

- ``glossary`` directive containing a definition list with terms and

12831

- definitions. It does not have to be in the same file as the ``term``

12832

- markup, in fact, by default the Python docs have one global glossary

12833

- in the ``glossary.rst`` file.

12834

-

12835

- If you use a term that's not explained in a glossary, you'll get a warning

12836

- during build.

12837

-

12838

----------

12839

-

12840

-The following roles don't do anything special except formatting the text

12841

-in a different style:

12842

-

12843

-.. describe:: command

12844

-

12845

- The name of an OS-level command, such as ``rm``.

12846

-

12847

-.. describe:: dfn

12848

-

12849

- Mark the defining instance of a term in the text. (No index entries are

12850

- generated.)

12851

-

12852

-.. describe:: envvar

12853

-

12854

- An environment variable. Index entries are generated.

12855

-

12856

-.. describe:: file

12857

-

12858

- The name of a file or directory. Within the contents, you can use curly

12859

- braces to indicate a "variable" part, for example::

12860

-

12861

- ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...

12862

-

12863

- In the built documentation, the ``x`` will be displayed differently to

12864

- indicate that it is to be replaced by the Python minor version.

12865

-

12866

-.. describe:: guilabel

12867

-

12868

- Labels presented as part of an interactive user interface should be marked

12869

- using ``guilabel``. This includes labels from text-based interfaces such as

12870

- those created using :mod:`curses` or other text-based libraries. Any label

12871

- used in the interface should be marked with this role, including button

12872

- labels, window titles, field names, menu and menu selection names, and even

12873

- values in selection lists.

12874

-

12875

-.. describe:: kbd

12876

-

12877

- Mark a sequence of keystrokes. What form the key sequence takes may depend

12878

- on platform- or application-specific conventions. When there are no relevant

12879

- conventions, the names of modifier keys should be spelled out, to improve

12880

- accessibility for new users and non-native speakers. For example, an

12881

- *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without

12882

- reference to a specific application or platform, the same sequence should be

12883

- marked as ``:kbd:`Control-x Control-f```.

12884

-

12885

-.. describe:: keyword

12886

-

12887

- The name of a keyword in Python.

12888

-

12889

-.. describe:: mailheader

12890

-

12891

- The name of an RFC 822-style mail header. This markup does not imply that

12892

- the header is being used in an email message, but can be used to refer to any

12893

- header of the same "style." This is also used for headers defined by the

12894

- various MIME specifications. The header name should be entered in the same

12895

- way it would normally be found in practice, with the camel-casing conventions

12896

- being preferred where there is more than one common usage. For example:

12897

- ``:mailheader:`Content-Type```.

12898

-

12899

-.. describe:: makevar

12900

-

12901

- The name of a :command:`make` variable.

12902

-

12903

-.. describe:: manpage

12904

-

12905

- A reference to a Unix manual page including the section,

12906

- e.g. ``:manpage:`ls(1)```.

12907

-

12908

-.. describe:: menuselection

12909

-

12910

- Menu selections should be marked using the ``menuselection`` role. This is

12911

- used to mark a complete sequence of menu selections, including selecting

12912

- submenus and choosing a specific operation, or any subsequence of such a

12913

- sequence. The names of individual selections should be separated by

12914

- ``-->``.

12915

-

12916

- For example, to mark the selection "Start > Programs", use this markup::

12917

-

12918

- :menuselection:`Start --> Programs`

12919

-

12920

- When including a selection that includes some trailing indicator, such as the

12921

- ellipsis some operating systems use to indicate that the command opens a

12922

- dialog, the indicator should be omitted from the selection name.

12923

-

12924

-.. describe:: mimetype

12925

-

12926

- The name of a MIME type, or a component of a MIME type (the major or minor

12927

- portion, taken alone).

12928

-

12929

-.. describe:: newsgroup

12930

-

12931

- The name of a Usenet newsgroup.

12932

-

12933

-.. describe:: option

12934

-

12935

- A command-line option of Python. The leading hyphen(s) must be included.

12936

- If a matching ``cmdoption`` directive exists, it is linked to. For options

12937

- of other programs or scripts, use simple ````code```` markup.

12938

-

12939

-.. describe:: program

12940

-

12941

- The name of an executable program. This may differ from the file name for

12942

- the executable for some platforms. In particular, the ``.exe`` (or other)

12943

- extension should be omitted for Windows programs.

12944

-

12945

-.. describe:: regexp

12946

-

12947

- A regular expression. Quotes should not be included.

12948

-

12949

-.. describe:: samp

12950

-

12951

- A piece of literal text, such as code. Within the contents, you can use

12952

- curly braces to indicate a "variable" part, as in ``:file:``.

12953

-

12954

- If you don't need the "variable part" indication, use the standard

12955

- ````code```` instead.

12956

-

12957

-

12958

-The following roles generate external links:

12959

-

12960

-.. describe:: pep

12961

-

12962

- A reference to a Python Enhancement Proposal. This generates appropriate

12963

- index entries. The text "PEP *number*\ " is generated; in the HTML output,

12964

- this text is a hyperlink to an online copy of the specified PEP.

12965

-

12966

-.. describe:: rfc

12967

-

12968

- A reference to an Internet Request for Comments. This generates appropriate

12969

- index entries. The text "RFC *number*\ " is generated; in the HTML output,

12970

- this text is a hyperlink to an online copy of the specified RFC.

12971

-

12972

-

12973

-Note that there are no special roles for including hyperlinks as you can use

12974

-the standard reST markup for that purpose.

12975

-

12976

-

12977

-.. _doc-ref-role:

12978

-

12979

-Cross-linking markup

12980

---------------------

12981

-

12982

-To support cross-referencing to arbitrary sections in the documentation, the

12983

-standard reST labels are "abused" a bit: Every label must precede a section

12984

-title; and every label name must be unique throughout the entire documentation

12985

-source.

12986

-

12987

-You can then reference to these sections using the ``:ref:`label-name``` role.

12988

-

12989

-Example::

12990

-

12991

- .. _my-reference-label:

12992

-

12993

- Section to cross-reference

12994

- --------------------------

12995

-

12996

- This is the text of the section.

12997

-

12998

- It refers to the section itself, see :ref:`my-reference-label`.

12999

-

13000

-The ``:ref:`` invocation is replaced with the section title.

13001

-

13002

-

13003

-Paragraph-level markup

13004

-----------------------

13005

-

13006

-These directives create short paragraphs and can be used inside information

13007

-units as well as normal text:

13008

-

13009

-.. describe:: note

13010

-

13011

- An especially important bit of information about an API that a user should be

13012

- aware of when using whatever bit of API the note pertains to. The content of

13013

- the directive should be written in complete sentences and include all

13014

- appropriate punctuation.

13015

-

13016

- Example::

13017

-

13018

- .. note::

13019

-

13020

- This function is not suitable for sending spam e-mails.

13021

-

13022

-.. describe:: warning

13023

-

13024

- An important bit of information about an API that a user should be aware of

13025

- when using whatever bit of API the warning pertains to. The content of the

13026

- directive should be written in complete sentences and include all appropriate

13027

- punctuation. In the interest of not scaring users away from pages filled

13028

- with warnings, this directive should only be chosen over ``note`` for

13029

- information regarding the possibility of crashes, data loss, or security

13030

- implications.

13031

-

13032

-.. describe:: versionadded

13033

-

13034

- This directive documents the version of Python which added the described

13035

- feature to the library or C API. When this applies to an entire module, it

13036

- should be placed at the top of the module section before any prose.

13037

-

13038

- The first argument must be given and is the version in question; you can add

13039

- a second argument consisting of a *brief* explanation of the change.

13040

-

13041

- Example::

13042

-

13043

- .. versionadded:: 2.5

13044

- The *spam* parameter.

13045

-

13046

- Note that there must be no blank line between the directive head and the

13047

- explanation; this is to make these blocks visually continuous in the markup.

13048

-

13049

-.. describe:: versionchanged

13050

-

13051

- Similar to ``versionadded``, but describes when and what changed in the named

13052

- feature in some way (new parameters, changed side effects, etc.).

13053

-

13054

---------------

13055

-

13056

-.. describe:: impl-detail

13057

-

13058

- This directive is used to mark CPython-specific information. Use either with

13059

- a block content or a single sentence as an argument, i.e. either ::

13060

-

13061

- .. impl-detail::

13062

-

13063

- This describes some implementation detail.

13064

-

13065

- More explanation.

13066

-

13067

- or ::

13068

-

13069

- .. impl-detail:: This shortly mentions an implementation detail.

13070

-

13071

- "\ **CPython implementation detail:**\ " is automatically prepended to the

13072

- content.

13073

-

13074

-.. describe:: seealso

13075

-

13076

- Many sections include a list of references to module documentation or

13077

- external documents. These lists are created using the ``seealso`` directive.

13078

-

13079

- The ``seealso`` directive is typically placed in a section just before any

13080

- sub-sections. For the HTML output, it is shown boxed off from the main flow

13081

- of the text.

13082

-

13083

- The content of the ``seealso`` directive should be a reST definition list.

13084

- Example::

13085

-

13086

- .. seealso::

13087

-

13088

- Module :mod:`zipfile`

13089

- Documentation of the :mod:`zipfile` standard module.

13090

-

13091

- `GNU tar manual, Basic Tar Format <http://link>`_

13092

- Documentation for tar archive files, including GNU tar extensions.

13093

-

13094

-.. describe:: rubric

13095

-

13096

- This directive creates a paragraph heading that is not used to create a

13097

- table of contents node. It is currently used for the "Footnotes" caption.

13098

-

13099

-.. describe:: centered

13100

-

13101

- This directive creates a centered boldfaced paragraph. Use it as follows::

13102

-

13103

- .. centered::

13104

-

13105

- Paragraph contents.

13106

-

13107

-

13108

-Table-of-contents markup

13109

-------------------------

13110

-

13111

-Since reST does not have facilities to interconnect several documents, or split

13112

-documents into multiple output files, Sphinx uses a custom directive to add

13113

-relations between the single files the documentation is made of, as well as

13114

-tables of contents. The ``toctree`` directive is the central element.

13115

-

13116

-.. describe:: toctree

13117

-

13118

- This directive inserts a "TOC tree" at the current location, using the

13119

- individual TOCs (including "sub-TOC trees") of the files given in the

13120

- directive body. A numeric ``maxdepth`` option may be given to indicate the

13121

- depth of the tree; by default, all levels are included.

13122

-

13123

- Consider this example (taken from the library reference index)::

13124

-

13125

- .. toctree::

13126

- :maxdepth: 2

13127

-

13128

- intro

13129

- strings

13130

- datatypes

13131

- numeric

13132

- (many more files listed here)

13133

-

13134

- This accomplishes two things:

13135

-

13136

- * Tables of contents from all those files are inserted, with a maximum depth

13137

- of two, that means one nested heading. ``toctree`` directives in those

13138

- files are also taken into account.

13139

- * Sphinx knows that the relative order of the files ``intro``,

13140

- ``strings`` and so forth, and it knows that they are children of the

13141

- shown file, the library index. From this information it generates "next

13142

- chapter", "previous chapter" and "parent chapter" links.

13143

-

13144

- In the end, all files included in the build process must occur in one

13145

- ``toctree`` directive; Sphinx will emit a warning if it finds a file that is

13146

- not included, because that means that this file will not be reachable through

13147

- standard navigation.

13148

-

13149

- The special file ``contents.rst`` at the root of the source directory is the

13150

- "root" of the TOC tree hierarchy; from it the "Contents" page is generated.

13151

-

13152

-

13153

-Index-generating markup

13154

------------------------

13155

-

13156

-Sphinx automatically creates index entries from all information units (like

13157

-functions, classes or attributes) like discussed before.

13158

-

13159

-However, there is also an explicit directive available, to make the index more

13160

-comprehensive and enable index entries in documents where information is not

13161

-mainly contained in information units, such as the language reference.

13162

-

13163

-The directive is ``index`` and contains one or more index entries. Each entry

13164

-consists of a type and a value, separated by a colon.

13165

-

13166

-For example::

13167

-

13168

- .. index::

13169

- single: execution; context

13170

- module: __main__

13171

- module: sys

13172

- triple: module; search; path

13173

-

13174

-This directive contains five entries, which will be converted to entries in the

13175

-generated index which link to the exact location of the index statement (or, in

13176

-case of offline media, the corresponding page number).

13177

-

13178

-The possible entry types are:

13179

-

13180

-single

13181

- Creates a single index entry. Can be made a subentry by separating the

13182

- subentry text with a semicolon (this notation is also used below to describe

13183

- what entries are created).

13184

-pair

13185

- ``pair: loop; statement`` is a shortcut that creates two index entries,

13186

- namely ``loop; statement`` and ``statement; loop``.

13187

-triple

13188

- Likewise, ``triple: module; search; path`` is a shortcut that creates three

13189

- index entries, which are ``module; search path``, ``search; path, module`` and

13190

- ``path; module search``.

13191

-module, keyword, operator, object, exception, statement, builtin

13192

- These all create two index entries. For example, ``module: hashlib`` creates

13193

- the entries ``module; hashlib`` and ``hashlib; module``.

13194

-

13195

-For index directives containing only "single" entries, there is a shorthand

13196

-notation::

13197

-

13198

- .. index:: BNF, grammar, syntax, notation

13199

-

13200

-This creates four index entries.

13201

-

13202

-

13203

-Grammar production displays

13204

----------------------------

13205

-

13206

-Special markup is available for displaying the productions of a formal grammar.

13207

-The markup is simple and does not attempt to model all aspects of BNF (or any

13208

-derived forms), but provides enough to allow context-free grammars to be

13209

-displayed in a way that causes uses of a symbol to be rendered as hyperlinks to

13210

-the definition of the symbol. There is this directive:

13211

-

13212

-.. describe:: productionlist

13213

-

13214

- This directive is used to enclose a group of productions. Each production is

13215

- given on a single line and consists of a name, separated by a colon from the

13216

- following definition. If the definition spans multiple lines, each

13217

- continuation line must begin with a colon placed at the same column as in the

13218

- first line.

13219

-

13220

- Blank lines are not allowed within ``productionlist`` directive arguments.

13221

-

13222

- The definition can contain token names which are marked as interpreted text

13223

- (e.g. ``unaryneg ::= "-" `integer```) -- this generates cross-references

13224

- to the productions of these tokens.

13225

-

13226

- Note that no further reST parsing is done in the production, so that you

13227

- don't have to escape ``*`` or ``|`` characters.

13228

-

13229

-

13230

-.. XXX describe optional first parameter

13231

-

13232

-The following is an example taken from the Python Reference Manual::

13233

-

13234

- .. productionlist::

13235

- try_stmt: try1_stmt | try2_stmt

13236

- try1_stmt: "try" ":" `suite`

13237

- : ("except" [`expression` ["," `target`]] ":" `suite`)+

13238

- : ["else" ":" `suite`]

13239

- : ["finally" ":" `suite`]

13240

- try2_stmt: "try" ":" `suite`

13241

- : "finally" ":" `suite`

13242

-

13243

-

13244

-Substitutions

13245

--------------

13246

-

13247

-The documentation system provides three substitutions that are defined by default.

13248

-They are set in the build configuration file :file:`conf.py`.

13249

-

13250

-.. describe:: |release|

13251

-

13252

- Replaced by the Python release the documentation refers to. This is the full

13253

- version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``.

13254

-

13255

-.. describe:: |version|

13256

-

13257

- Replaced by the Python version the documentation refers to. This consists

13258

- only of the major and minor version parts, e.g. ``2.5``, even for version

13259

- 2.5.1.

13260

-

13261

-.. describe:: |today|

13262

-

13263

- Replaced by either today's date, or the date set in the build configuration

13264

- file. Normally has the format ``April 14, 2007``.

13265

-

13266

-

13267

-.. rubric:: Footnotes

13268

-

13269

-.. [1] There is a standard ``.. include`` directive, but it raises errors if the

13270

- file is not found. This one only emits a warning.

13271

diff -r 8527427914a2 Doc/documenting/rest.rst

13272

--- a/Doc/documenting/rest.rst

13273

+++ /dev/null

13274

@@ -1,243 +0,0 @@

13275

-.. highlightlang:: rest

13276

-

13277

-reStructuredText Primer

13278

-=======================

13279

-

13280

-This section is a brief introduction to reStructuredText (reST) concepts and

13281

-syntax, intended to provide authors with enough information to author documents

13282

-productively. Since reST was designed to be a simple, unobtrusive markup

13283

-language, this will not take too long.

13284

-

13285

-.. seealso::

13286

-

13287

- The authoritative `reStructuredText User

13288

- Documentation <http://docutils.sourceforge.net/rst.html>`_.

13289

-

13290

-

13291

-Paragraphs

13292

-----------

13293

-

13294

-The paragraph is the most basic block in a reST document. Paragraphs are simply

13295

-chunks of text separated by one or more blank lines. As in Python, indentation

13296

-is significant in reST, so all lines of the same paragraph must be left-aligned

13297

-to the same level of indentation.

13298

-

13299

-

13300

-Inline markup

13301

--------------

13302

-

13303

-The standard reST inline markup is quite simple: use

13304

-

13305

-* one asterisk: ``*text*`` for emphasis (italics),

13306

-* two asterisks: ``**text**`` for strong emphasis (boldface), and

13307

-* backquotes: ````text```` for code samples.

13308

-

13309

-If asterisks or backquotes appear in running text and could be confused with

13310

-inline markup delimiters, they have to be escaped with a backslash.

13311

-

13312

-Be aware of some restrictions of this markup:

13313

-

13314

-* it may not be nested,

13315

-* content may not start or end with whitespace: ``* text*`` is wrong,

13316

-* it must be separated from surrounding text by non-word characters. Use a

13317

- backslash escaped space to work around that: ``thisis\ *one*\ word``.

13318

-

13319

-These restrictions may be lifted in future versions of the docutils.

13320

-

13321

-reST also allows for custom "interpreted text roles"', which signify that the

13322

-enclosed text should be interpreted in a specific way. Sphinx uses this to

13323

-provide semantic markup and cross-referencing of identifiers, as described in

13324

-the appropriate section. The general syntax is ``:rolename:`content```.

13325

-

13326

-

13327

-Lists and Quotes

13328

-----------------

13329

-

13330

-List markup is natural: just place an asterisk at the start of a paragraph and

13331

-indent properly. The same goes for numbered lists; they can also be

13332

-autonumbered using a ``#`` sign::

13333

-

13334

- * This is a bulleted list.

13335

- * It has two items, the second

13336

- item uses two lines.

13337

-

13338

- 1. This is a numbered list.

13339

- 2. It has two items too.

13340

-

13341

- #. This is a numbered list.

13342

- #. It has two items too.

13343

-

13344

-

13345

-Nested lists are possible, but be aware that they must be separated from the

13346

-parent list items by blank lines::

13347

-

13348

- * this is

13349

- * a list

13350

-

13351

- * with a nested list

13352

- * and some subitems

13353

-

13354

- * and here the parent list continues

13355

-

13356

-Definition lists are created as follows::

13357

-

13358

- term (up to a line of text)

13359

- Definition of the term, which must be indented

13360

-

13361

- and can even consist of multiple paragraphs

13362

-

13363

- next term

13364

- Description.

13365

-

13366

-

13367

-Paragraphs are quoted by just indenting them more than the surrounding

13368

-paragraphs.

13369

-

13370

-

13371

-Source Code

13372

------------

13373

-

13374

-Literal code blocks are introduced by ending a paragraph with the special marker

13375

-``::``. The literal block must be indented::

13376

-

13377

- This is a normal text paragraph. The next paragraph is a code sample::

13378

-

13379

- It is not processed in any way, except

13380

- that the indentation is removed.

13381

-

13382

- It can span multiple lines.

13383

-

13384

- This is a normal text paragraph again.

13385

-

13386

-The handling of the ``::`` marker is smart:

13387

-

13388

-* If it occurs as a paragraph of its own, that paragraph is completely left

13389

- out of the document.

13390

-* If it is preceded by whitespace, the marker is removed.

13391

-* If it is preceded by non-whitespace, the marker is replaced by a single

13392

- colon.

13393

-

13394

-That way, the second sentence in the above example's first paragraph would be

13395

-rendered as "The next paragraph is a code sample:".

13396

-

13397

-

13398

-Hyperlinks

13399

-----------

13400

-

13401

-External links

13402

-^^^^^^^^^^^^^^

13403

-

13404

-Use ```Link text <http://target>`_`` for inline web links. If the link text

13405

-should be the web address, you don't need special markup at all, the parser

13406

-finds links and mail addresses in ordinary text.

13407

-

13408

-Internal links

13409

-^^^^^^^^^^^^^^

13410

-

13411

-Internal linking is done via a special reST role, see the section on specific

13412

-markup, :ref:`doc-ref-role`.

13413

-

13414

-

13415

-Sections

13416

---------

13417

-

13418

-Section headers are created by underlining (and optionally overlining) the

13419

-section title with a punctuation character, at least as long as the text::

13420

-

13421

- =================

13422

- This is a heading

13423

- =================

13424

-

13425

-Normally, there are no heading levels assigned to certain characters as the

13426

-structure is determined from the succession of headings. However, for the

13427

-Python documentation, we use this convention:

13428

-

13429

-* ``#`` with overline, for parts

13430

-* ``*`` with overline, for chapters

13431

-* ``=``, for sections

13432

-* ``-``, for subsections

13433

-* ``^``, for subsubsections

13434

-* ``"``, for paragraphs

13435

-

13436

-

13437

-Explicit Markup

13438

----------------

13439

-

13440

-"Explicit markup" is used in reST for most constructs that need special

13441

-handling, such as footnotes, specially-highlighted paragraphs, comments, and

13442

-generic directives.

13443

-

13444

-An explicit markup block begins with a line starting with ``..`` followed by

13445

-whitespace and is terminated by the next paragraph at the same level of

13446

-indentation. (There needs to be a blank line between explicit markup and normal

13447

-paragraphs. This may all sound a bit complicated, but it is intuitive enough

13448

-when you write it.)

13449

-

13450

-

13451

-Directives

13452

-----------

13453

-

13454

-A directive is a generic block of explicit markup. Besides roles, it is one of

13455

-the extension mechanisms of reST, and Sphinx makes heavy use of it.

13456

-

13457

-Basically, a directive consists of a name, arguments, options and content. (Keep

13458

-this terminology in mind, it is used in the next chapter describing custom

13459

-directives.) Looking at this example, ::

13460

-

13461

- .. function:: foo(x)

13462

- foo(y, z)

13463

- :bar: no

13464

-

13465

- Return a line of text input from the user.

13466

-

13467

-``function`` is the directive name. It is given two arguments here, the

13468

-remainder of the first line and the second line, as well as one option ``bar``

13469

-(as you can see, options are given in the lines immediately following the

13470

-arguments and indicated by the colons).

13471

-

13472

-The directive content follows after a blank line and is indented relative to the

13473

-directive start.

13474

-

13475

-

13476

-Footnotes

13477

----------

13478

-

13479

-For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote

13480

-body at the bottom of the document after a "Footnotes" rubric heading, like so::

13481

-

13482

- Lorem ipsum [#]_ dolor sit amet ... [#]_

13483

-

13484

- .. rubric:: Footnotes

13485

-

13486

- .. [#] Text of the first footnote.

13487

- .. [#] Text of the second footnote.

13488

-

13489

-You can also explicitly number the footnotes for better context.

13490

-

13491

-

13492

-Comments

13493

---------

13494

-

13495

-Every explicit markup block which isn't a valid markup construct (like the

13496

-footnotes above) is regarded as a comment.

13497

-

13498

-

13499

-Source encoding

13500

----------------

13501

-

13502

-Since the easiest way to include special characters like em dashes or copyright

13503

-signs in reST is to directly write them as Unicode characters, one has to

13504

-specify an encoding:

13505

-

13506

-All Python documentation source files must be in UTF-8 encoding, and the HTML

13507

-documents written from them will be in that encoding as well.

13508

-

13509

-

13510

-Gotchas

13511

--------

13512

-

13513

-There are some problems one commonly runs into while authoring reST documents:

13514

-

13515

-* **Separation of inline markup:** As said above, inline markup spans must be

13516

- separated from the surrounding text by non-word characters, you have to use

13517

- an escaped space to get around that.

13518

diff -r 8527427914a2 Doc/documenting/style.rst

13519

--- a/Doc/documenting/style.rst

13520

+++ /dev/null

13521

@@ -1,174 +0,0 @@

13522

-.. highlightlang:: rest

13523

-

13524

-Style Guide

13525

-===========

13526

-

13527

-The Python documentation should follow the `Apple Publications Style Guide`_

13528

-wherever possible. This particular style guide was selected mostly because it

13529

-seems reasonable and is easy to get online.

13530

-

13531

-Topics which are not covered in Apple's style guide will be discussed in

13532

-this document.

13533

-

13534

-All reST files use an indentation of 3 spaces. The maximum line length is 80

13535

-characters for normal text, but tables, deeply indented code samples and long

13536

-links may extend beyond that.

13537

-

13538

-Make generous use of blank lines where applicable; they help grouping things

13539

-together.

13540

-

13541

-A sentence-ending period may be followed by one or two spaces; while reST

13542

-ignores the second space, it is customarily put in by some users, for example

13543

-to aid Emacs' auto-fill mode.

13544

-

13545

-Footnotes are generally discouraged, though they may be used when they are the

13546

-best way to present specific information. When a footnote reference is added at

13547

-the end of the sentence, it should follow the sentence-ending punctuation. The

13548

-reST markup should appear something like this::

13549

-

13550

- This sentence has a footnote reference. [#]_ This is the next sentence.

13551

-

13552

-Footnotes should be gathered at the end of a file, or if the file is very long,

13553

-at the end of a section. The docutils will automatically create backlinks to

13554

-the footnote reference.

13555

-

13556

-Footnotes may appear in the middle of sentences where appropriate.

13557

-

13558

-Many special names are used in the Python documentation, including the names of

13559

-operating systems, programming languages, standards bodies, and the like. Most

13560

-of these entities are not assigned any special markup, but the preferred

13561

-spellings are given here to aid authors in maintaining the consistency of

13562

-presentation in the Python documentation.

13563

-

13564

-Other terms and words deserve special mention as well; these conventions should

13565

-be used to ensure consistency throughout the documentation:

13566

-

13567

-CPU

13568

- For "central processing unit." Many style guides say this should be spelled

13569

- out on the first use (and if you must use it, do so!). For the Python

13570

- documentation, this abbreviation should be avoided since there's no

13571

- reasonable way to predict which occurrence will be the first seen by the

13572

- reader. It is better to use the word "processor" instead.

13573

-

13574

-POSIX

13575

- The name assigned to a particular group of standards. This is always

13576

- uppercase.

13577

-

13578

-Python

13579

- The name of our favorite programming language is always capitalized.

13580

-

13581

-Unicode

13582

- The name of a character set and matching encoding. This is always written

13583

- capitalized.

13584

-

13585

-Unix

13586

- The name of the operating system developed at AT&T Bell Labs in the early

13587

- 1970s.

13588

-

13589

-Affirmative Tone

13590

-----------------

13591

-

13592

-The documentation focuses on affirmatively stating what the language does and

13593

-how to use it effectively.

13594

-

13595

-Except for certain security risks or segfault risks, the docs should avoid

13596

-wording along the lines of "feature x is dangerous" or "experts only". These

13597

-kinds of value judgments belong in external blogs and wikis, not in the core

13598

-documentation.

13599

-

13600

-Bad example (creating worry in the mind of a reader):

13601

-

13602

- Warning: failing to explicitly close a file could result in lost data or

13603

- excessive resource consumption. Never rely on reference counting to

13604

- automatically close a file.

13605

-

13606

-Good example (establishing confident knowledge in the effective use of the language):

13607

-

13608

- A best practice for using files is use a try/finally pair to explicitly

13609

- close a file after it is used. Alternatively, using a with-statement can

13610

- achieve the same effect. This assures that files are flushed and file

13611

- descriptor resources are released in a timely manner.

13612

-

13613

-Economy of Expression

13614

----------------------

13615

-

13616

-More documentation is not necessarily better documentation. Err on the side

13617

-of being succinct.

13618

-

13619

-It is an unfortunate fact that making documentation longer can be an impediment

13620

-to understanding and can result in even more ways to misread or misinterpret the

13621

-text. Long descriptions full of corner cases and caveats can create the

13622

-impression that a function is more complex or harder to use than it actually is.

13623

-

13624

-The documentation for :func:`super` is an example of where a good deal of

13625

-information was condensed into a few short paragraphs. Discussion of

13626

-:func:`super` could have filled a chapter in a book, but it is often easier to

13627

-grasp a terse description than a lengthy narrative.

13628

-

13629

-

13630

-Code Examples

13631

--------------

13632

-

13633

-Short code examples can be a useful adjunct to understanding. Readers can often

13634

-grasp a simple example more quickly than they can digest a formal description in

13635

-prose.

13636

-

13637

-People learn faster with concrete, motivating examples that match the context of

13638

-a typical use case. For instance, the :func:`str.rpartition` method is better

13639

-demonstrated with an example splitting the domain from a URL than it would be

13640

-with an example of removing the last word from a line of Monty Python dialog.

13641

-

13642

-The ellipsis for the :attr:`sys.ps2` secondary interpreter prompt should only be

13643

-used sparingly, where it is necessary to clearly differentiate between input

13644

-lines and output lines. Besides contributing visual clutter, it makes it

13645

-difficult for readers to cut-and-paste examples so they can experiment with

13646

-variations.

13647

-

13648

-Code Equivalents

13649

-----------------

13650

-

13651

-Giving pure Python code equivalents (or approximate equivalents) can be a useful

13652

-adjunct to a prose description. A documenter should carefully weigh whether the

13653

-code equivalent adds value.

13654

-

13655

-A good example is the code equivalent for :func:`all`. The short 4-line code

13656

-equivalent is easily digested; it re-emphasizes the early-out behavior; and it

13657

-clarifies the handling of the corner-case where the iterable is empty. In

13658

-addition, it serves as a model for people wanting to implement a commonly

13659

-requested alternative where :func:`all` would return the specific object

13660

-evaluating to False whenever the function terminates early.

13661

-

13662

-A more questionable example is the code for :func:`itertools.groupby`. Its code

13663

-equivalent borders on being too complex to be a quick aid to understanding.

13664

-Despite its complexity, the code equivalent was kept because it serves as a

13665

-model to alternative implementations and because the operation of the "grouper"

13666

-is more easily shown in code than in English prose.

13667

-

13668

-An example of when not to use a code equivalent is for the :func:`oct` function.

13669

-The exact steps in converting a number to octal doesn't add value for a user

13670

-trying to learn what the function does.

13671

-

13672

-Audience

13673

---------

13674

-

13675

-The tone of the tutorial (and all the docs) needs to be respectful of the

13676

-reader's intelligence. Don't presume that the readers are stupid. Lay out the

13677

-relevant information, show motivating use cases, provide glossary links, and do

13678

-your best to connect the dots, but don't talk down to them or waste their time.

13679

-

13680

-The tutorial is meant for newcomers, many of whom will be using the tutorial to

13681

-evaluate the language as a whole. The experience needs to be positive and not

13682

-leave the reader with worries that something bad will happen if they make a

13683

-misstep. The tutorial serves as guide for intelligent and curious readers,

13684

-saving details for the how-to guides and other sources.

13685

-

13686

-Be careful accepting requests for documentation changes from the rare but vocal

13687

-category of reader who is looking for vindication for one of their programming

13688

-errors ("I made a mistake, therefore the docs must be wrong ..."). Typically,

13689

-the documentation wasn't consulted until after the error was made. It is

13690

-unfortunate, but typically no documentation edit would have saved the user from

13691

-making false assumptions about the language ("I was surprised by ...").

13692

-

13693

-

13694

-.. _Apple Publications Style Guide: http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf

13695

-

13696

diff -r 8527427914a2 Doc/extending/embedding.rst

13697

--- a/Doc/extending/embedding.rst

13698

+++ b/Doc/extending/embedding.rst

13699

@@ -25,14 +25,14 @@

13700

13701

So if you are embedding Python, you are providing your own main program. One of

13702

the things this main program has to do is initialize the Python interpreter. At

13703

-the very least, you have to call the function :cfunc:`Py_Initialize`. There are

13704

+the very least, you have to call the function :c:func:`Py_Initialize`. There are

13705

optional calls to pass command line arguments to Python. Then later you can

13706

call the interpreter from any part of the application.

13707

13708

There are several different ways to call the interpreter: you can pass a string

13709

-containing Python statements to :cfunc:`PyRun_SimpleString`, or you can pass a

13710

+containing Python statements to :c:func:`PyRun_SimpleString`, or you can pass a

13711

stdio file pointer and a file name (for identification in error messages only)

13712

-to :cfunc:`PyRun_SimpleFile`. You can also call the lower-level operations

13713

+to :c:func:`PyRun_SimpleFile`. You can also call the lower-level operations

13714

described in the previous chapters to construct and use Python objects.

13715

13716

A simple demo of embedding Python can be found in the directory

13717

@@ -69,12 +69,12 @@

13718

}

13719

13720

The above code first initializes the Python interpreter with

13721

-:cfunc:`Py_Initialize`, followed by the execution of a hard-coded Python script

13722

-that print the date and time. Afterwards, the :cfunc:`Py_Finalize` call shuts

13723

+:c:func:`Py_Initialize`, followed by the execution of a hard-coded Python script

13724

+that print the date and time. Afterwards, the :c:func:`Py_Finalize` call shuts

13725

the interpreter down, followed by the end of the program. In a real program,

13726

you may want to get the Python script from another source, perhaps a text-editor

13727

routine, a file, or a database. Getting the Python code from a file can better

13728

-be done by using the :cfunc:`PyRun_SimpleFile` function, which saves you the

13729

+be done by using the :c:func:`PyRun_SimpleFile` function, which saves you the

13730

trouble of allocating memory space and loading the file contents.

13731

13732

13733

@@ -162,8 +162,8 @@

13734

pModule = PyImport_Import(pName);

13735

13736

After initializing the interpreter, the script is loaded using

13737

-:cfunc:`PyImport_Import`. This routine needs a Python string as its argument,

13738

-which is constructed using the :cfunc:`PyString_FromString` data conversion

13739

+:c:func:`PyImport_Import`. This routine needs a Python string as its argument,

13740

+which is constructed using the :c:func:`PyString_FromString` data conversion

13741

routine. ::

13742

13743

pFunc = PyObject_GetAttrString(pModule, argv[2]);

13744

@@ -175,7 +175,7 @@

13745

Py_XDECREF(pFunc);

13746

13747

Once the script is loaded, the name we're looking for is retrieved using

13748

-:cfunc:`PyObject_GetAttrString`. If the name exists, and the object returned is

13749

+:c:func:`PyObject_GetAttrString`. If the name exists, and the object returned is

13750

callable, you can safely assume that it is a function. The program then

13751

proceeds by constructing a tuple of arguments as normal. The call to the Python

13752

function is then made with::

13753

@@ -218,8 +218,8 @@

13754

{NULL, NULL, 0, NULL}

13755

};

13756

13757

-Insert the above code just above the :cfunc:`main` function. Also, insert the

13758

-following two statements directly after :cfunc:`Py_Initialize`::

13759

+Insert the above code just above the :c:func:`main` function. Also, insert the

13760

+following two statements directly after :c:func:`Py_Initialize`::

13761

13762

numargs = argc;

13763

Py_InitModule("emb", EmbMethods);

13764

diff -r 8527427914a2 Doc/extending/extending.rst

13765

--- a/Doc/extending/extending.rst

13766

+++ b/Doc/extending/extending.rst

13767

@@ -35,7 +35,7 @@

13768

13769

Let's create an extension module called ``spam`` (the favorite food of Monty

13770

Python fans...) and let's say we want to create a Python interface to the C

13771

-library function :cfunc:`system`. [#]_ This function takes a null-terminated

13772

+library function :c:func:`system`. [#]_ This function takes a null-terminated

13773

character string as argument and returns an integer. We want this function to

13774

be callable from Python as follows::

13775

13776

@@ -65,8 +65,8 @@

13777

since they are used extensively by the Python interpreter, ``"Python.h"``

13778

includes a few standard header files: ``<stdio.h>``, ``<string.h>``,

13779

``<errno.h>``, and ``<stdlib.h>``. If the latter header file does not exist on

13780

-your system, it declares the functions :cfunc:`malloc`, :cfunc:`free` and

13781

-:cfunc:`realloc` directly.

13782

+your system, it declares the functions :c:func:`malloc`, :c:func:`free` and

13783

+:c:func:`realloc` directly.

13784

13785

The next thing we add to our module file is the C function that will be called

13786

when the Python expression ``spam.system(string)`` is evaluated (we'll see

13787

@@ -96,12 +96,12 @@

13788

arguments. Each item of the tuple corresponds to an argument in the call's

13789

argument list. The arguments are Python objects --- in order to do anything

13790

with them in our C function we have to convert them to C values. The function

13791

-:cfunc:`PyArg_ParseTuple` in the Python API checks the argument types and

13792

+:c:func:`PyArg_ParseTuple` in the Python API checks the argument types and

13793

converts them to C values. It uses a template string to determine the required

13794

types of the arguments as well as the types of the C variables into which to

13795

store the converted values. More about this later.

13796

13797

-:cfunc:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the right

13798

+:c:func:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the right

13799

type and its components have been stored in the variables whose addresses are

13800

passed. It returns false (zero) if an invalid argument list was passed. In the

13801

latter case it also raises an appropriate exception so the calling function can

13802

@@ -127,77 +127,77 @@

13803

13804

The Python API defines a number of functions to set various types of exceptions.

13805

13806

-The most common one is :cfunc:`PyErr_SetString`. Its arguments are an exception

13807

+The most common one is :c:func:`PyErr_SetString`. Its arguments are an exception

13808

object and a C string. The exception object is usually a predefined object like

13809

-:cdata:`PyExc_ZeroDivisionError`. The C string indicates the cause of the error

13810

+:c:data:`PyExc_ZeroDivisionError`. The C string indicates the cause of the error

13811

and is converted to a Python string object and stored as the "associated value"

13812

of the exception.

13813

13814

-Another useful function is :cfunc:`PyErr_SetFromErrno`, which only takes an

13815

+Another useful function is :c:func:`PyErr_SetFromErrno`, which only takes an

13816

exception argument and constructs the associated value by inspection of the

13817

-global variable :cdata:`errno`. The most general function is

13818

-:cfunc:`PyErr_SetObject`, which takes two object arguments, the exception and

13819

-its associated value. You don't need to :cfunc:`Py_INCREF` the objects passed

13820

+global variable :c:data:`errno`. The most general function is

13821

+:c:func:`PyErr_SetObject`, which takes two object arguments, the exception and

13822

+its associated value. You don't need to :c:func:`Py_INCREF` the objects passed

13823

to any of these functions.

13824

13825

You can test non-destructively whether an exception has been set with

13826

-:cfunc:`PyErr_Occurred`. This returns the current exception object, or *NULL*

13827

+:c:func:`PyErr_Occurred`. This returns the current exception object, or *NULL*

13828

if no exception has occurred. You normally don't need to call

13829

-:cfunc:`PyErr_Occurred` to see whether an error occurred in a function call,

13830

+:c:func:`PyErr_Occurred` to see whether an error occurred in a function call,

13831

since you should be able to tell from the return value.

13832

13833

When a function *f* that calls another function *g* detects that the latter

13834

fails, *f* should itself return an error value (usually *NULL* or ``-1``). It

13835

-should *not* call one of the :cfunc:`PyErr_\*` functions --- one has already

13836

+should *not* call one of the :c:func:`PyErr_\*` functions --- one has already

13837

been called by *g*. *f*'s caller is then supposed to also return an error

13838

-indication to *its* caller, again *without* calling :cfunc:`PyErr_\*`, and so on

13839

+indication to *its* caller, again *without* calling :c:func:`PyErr_\*`, and so on

13840

--- the most detailed cause of the error was already reported by the function

13841

that first detected it. Once the error reaches the Python interpreter's main

13842

loop, this aborts the currently executing Python code and tries to find an

13843

exception handler specified by the Python programmer.

13844

13845

(There are situations where a module can actually give a more detailed error

13846

-message by calling another :cfunc:`PyErr_\*` function, and in such cases it is

13847

+message by calling another :c:func:`PyErr_\*` function, and in such cases it is

13848

fine to do so. As a general rule, however, this is not necessary, and can cause

13849

information about the cause of the error to be lost: most operations can fail

13850

for a variety of reasons.)

13851

13852

To ignore an exception set by a function call that failed, the exception

13853

-condition must be cleared explicitly by calling :cfunc:`PyErr_Clear`. The only

13854

-time C code should call :cfunc:`PyErr_Clear` is if it doesn't want to pass the

13855

+condition must be cleared explicitly by calling :c:func:`PyErr_Clear`. The only

13856

+time C code should call :c:func:`PyErr_Clear` is if it doesn't want to pass the

13857

error on to the interpreter but wants to handle it completely by itself

13858

(possibly by trying something else, or pretending nothing went wrong).

13859

13860

-Every failing :cfunc:`malloc` call must be turned into an exception --- the

13861

-direct caller of :cfunc:`malloc` (or :cfunc:`realloc`) must call

13862

-:cfunc:`PyErr_NoMemory` and return a failure indicator itself. All the

13863

-object-creating functions (for example, :cfunc:`PyInt_FromLong`) already do

13864

-this, so this note is only relevant to those who call :cfunc:`malloc` directly.

13865

+Every failing :c:func:`malloc` call must be turned into an exception --- the

13866

+direct caller of :c:func:`malloc` (or :c:func:`realloc`) must call

13867

+:c:func:`PyErr_NoMemory` and return a failure indicator itself. All the

13868

+object-creating functions (for example, :c:func:`PyInt_FromLong`) already do

13869

+this, so this note is only relevant to those who call :c:func:`malloc` directly.

13870

13871

-Also note that, with the important exception of :cfunc:`PyArg_ParseTuple` and

13872

+Also note that, with the important exception of :c:func:`PyArg_ParseTuple` and

13873

friends, functions that return an integer status usually return a positive value

13874

or zero for success and ``-1`` for failure, like Unix system calls.

13875

13876

-Finally, be careful to clean up garbage (by making :cfunc:`Py_XDECREF` or

13877

-:cfunc:`Py_DECREF` calls for objects you have already created) when you return

13878

+Finally, be careful to clean up garbage (by making :c:func:`Py_XDECREF` or

13879

+:c:func:`Py_DECREF` calls for objects you have already created) when you return

13880

an error indicator!

13881

13882

The choice of which exception to raise is entirely yours. There are predeclared

13883

C objects corresponding to all built-in Python exceptions, such as

13884

-:cdata:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you

13885

-should choose exceptions wisely --- don't use :cdata:`PyExc_TypeError` to mean

13886

-that a file couldn't be opened (that should probably be :cdata:`PyExc_IOError`).

13887

-If something's wrong with the argument list, the :cfunc:`PyArg_ParseTuple`

13888

-function usually raises :cdata:`PyExc_TypeError`. If you have an argument whose

13889

+:c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you

13890

+should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` to mean

13891

+that a file couldn't be opened (that should probably be :c:data:`PyExc_IOError`).

13892

+If something's wrong with the argument list, the :c:func:`PyArg_ParseTuple`

13893

+function usually raises :c:data:`PyExc_TypeError`. If you have an argument whose

13894

value must be in a particular range or must satisfy other conditions,

13895

-:cdata:`PyExc_ValueError` is appropriate.

13896

+:c:data:`PyExc_ValueError` is appropriate.

13897

13898

You can also define a new exception that is unique to your module. For this, you

13899

usually declare a static object variable at the beginning of your file::

13900

13901

static PyObject *SpamError;

13902

13903

-and initialize it in your module's initialization function (:cfunc:`initspam`)

13904

+and initialize it in your module's initialization function (:c:func:`initspam`)

13905

with an exception object (leaving out the error checking for now)::

13906

13907

PyMODINIT_FUNC

13908

@@ -215,14 +215,14 @@

13909

}

13910

13911

Note that the Python name for the exception object is :exc:`spam.error`. The

13912

-:cfunc:`PyErr_NewException` function may create a class with the base class

13913

+:c:func:`PyErr_NewException` function may create a class with the base class

13914

being :exc:`Exception` (unless another class is passed in instead of *NULL*),

13915

described in :ref:`bltin-exceptions`.

13916

13917

-Note also that the :cdata:`SpamError` variable retains a reference to the newly

13918

+Note also that the :c:data:`SpamError` variable retains a reference to the newly

13919

created exception class; this is intentional! Since the exception could be

13920

removed from the module by external code, an owned reference to the class is

13921

-needed to ensure that it will not be discarded, causing :cdata:`SpamError` to

13922

+needed to ensure that it will not be discarded, causing :c:data:`SpamError` to

13923

become a dangling pointer. Should it become a dangling pointer, C code which

13924

raises the exception could cause a core dump or other unintended side effects.

13925

13926

@@ -230,7 +230,7 @@

13927

sample.

13928

13929

The :exc:`spam.error` exception can be raised in your extension module using a

13930

-call to :cfunc:`PyErr_SetString` as shown below::

13931

+call to :c:func:`PyErr_SetString` as shown below::

13932

13933

static PyObject *

13934

spam_system(PyObject *self, PyObject *args)

13935

@@ -262,22 +262,22 @@

13936

13937

It returns *NULL* (the error indicator for functions returning object pointers)

13938

if an error is detected in the argument list, relying on the exception set by

13939

-:cfunc:`PyArg_ParseTuple`. Otherwise the string value of the argument has been

13940

-copied to the local variable :cdata:`command`. This is a pointer assignment and

13941

+:c:func:`PyArg_ParseTuple`. Otherwise the string value of the argument has been

13942

+copied to the local variable :c:data:`command`. This is a pointer assignment and

13943

you are not supposed to modify the string to which it points (so in Standard C,

13944

-the variable :cdata:`command` should properly be declared as ``const char

13945

+the variable :c:data:`command` should properly be declared as ``const char

13946

*command``).

13947

13948

-The next statement is a call to the Unix function :cfunc:`system`, passing it

13949

-the string we just got from :cfunc:`PyArg_ParseTuple`::

13950

+The next statement is a call to the Unix function :c:func:`system`, passing it

13951

+the string we just got from :c:func:`PyArg_ParseTuple`::

13952

13953

sts = system(command);

13954

13955

-Our :func:`spam.system` function must return the value of :cdata:`sts` as a

13956

-Python object. This is done using the function :cfunc:`Py_BuildValue`, which is

13957

-something like the inverse of :cfunc:`PyArg_ParseTuple`: it takes a format

13958

+Our :func:`spam.system` function must return the value of :c:data:`sts` as a

13959

+Python object. This is done using the function :c:func:`Py_BuildValue`, which is

13960

+something like the inverse of :c:func:`PyArg_ParseTuple`: it takes a format

13961

string and an arbitrary number of C values, and returns a new Python object.

13962

-More info on :cfunc:`Py_BuildValue` is given later. ::

13963

+More info on :c:func:`Py_BuildValue` is given later. ::

13964

13965

return Py_BuildValue("i", sts);

13966

13967

@@ -285,14 +285,14 @@

13968

on the heap in Python!)

13969

13970

If you have a C function that returns no useful argument (a function returning

13971

-:ctype:`void`), the corresponding Python function must return ``None``. You

13972

-need this idiom to do so (which is implemented by the :cmacro:`Py_RETURN_NONE`

13973

+:c:type:`void`), the corresponding Python function must return ``None``. You

13974

+need this idiom to do so (which is implemented by the :c:macro:`Py_RETURN_NONE`

13975

macro)::

13976

13977

Py_INCREF(Py_None);

13978

return Py_None;

13979

13980

-:cdata:`Py_None` is the C name for the special Python object ``None``. It is a

13981

+:c:data:`Py_None` is the C name for the special Python object ``None``. It is a

13982

genuine Python object rather than a *NULL* pointer, which means "error" in most

13983

contexts, as we have seen.

13984

13985

@@ -302,7 +302,7 @@

13986

The Module's Method Table and Initialization Function

13987

=====================================================

13988

13989

-I promised to show how :cfunc:`spam_system` is called from Python programs.

13990

+I promised to show how :c:func:`spam_system` is called from Python programs.

13991

First, we need to list its name and address in a "method table"::

13992

13993

static PyMethodDef SpamMethods[] = {

13994

@@ -316,21 +316,21 @@

13995

Note the third entry (``METH_VARARGS``). This is a flag telling the interpreter

13996

the calling convention to be used for the C function. It should normally always

13997

be ``METH_VARARGS`` or ``METH_VARARGS | METH_KEYWORDS``; a value of ``0`` means

13998

-that an obsolete variant of :cfunc:`PyArg_ParseTuple` is used.

13999

+that an obsolete variant of :c:func:`PyArg_ParseTuple` is used.

14000

14001

When using only ``METH_VARARGS``, the function should expect the Python-level

14002

parameters to be passed in as a tuple acceptable for parsing via

14003

-:cfunc:`PyArg_ParseTuple`; more information on this function is provided below.

14004

+:c:func:`PyArg_ParseTuple`; more information on this function is provided below.

14005

14006

The :const:`METH_KEYWORDS` bit may be set in the third field if keyword

14007

arguments should be passed to the function. In this case, the C function should

14008

accept a third ``PyObject *`` parameter which will be a dictionary of keywords.

14009

-Use :cfunc:`PyArg_ParseTupleAndKeywords` to parse the arguments to such a

14010

+Use :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments to such a

14011

function.

14012

14013

The method table must be passed to the interpreter in the module's

14014

initialization function. The initialization function must be named

14015

-:cfunc:`initname`, where *name* is the name of the module, and should be the

14016

+:c:func:`initname`, where *name* is the name of the module, and should be the

14017

only non-\ ``static`` item defined in the module file::

14018

14019

PyMODINIT_FUNC

14020

@@ -344,21 +344,21 @@

14021

declares the function as ``extern "C"``.

14022

14023

When the Python program imports module :mod:`spam` for the first time,

14024

-:cfunc:`initspam` is called. (See below for comments about embedding Python.)

14025

-It calls :cfunc:`Py_InitModule`, which creates a "module object" (which is

14026

+:c:func:`initspam` is called. (See below for comments about embedding Python.)

14027

+It calls :c:func:`Py_InitModule`, which creates a "module object" (which is

14028

inserted in the dictionary ``sys.modules`` under the key ``"spam"``), and

14029

inserts built-in function objects into the newly created module based upon the

14030

-table (an array of :ctype:`PyMethodDef` structures) that was passed as its

14031

-second argument. :cfunc:`Py_InitModule` returns a pointer to the module object

14032

+table (an array of :c:type:`PyMethodDef` structures) that was passed as its

14033

+second argument. :c:func:`Py_InitModule` returns a pointer to the module object

14034

that it creates (which is unused here). It may abort with a fatal error for

14035

certain errors, or return *NULL* if the module could not be initialized

14036

satisfactorily.

14037

14038

-When embedding Python, the :cfunc:`initspam` function is not called

14039

-automatically unless there's an entry in the :cdata:`_PyImport_Inittab` table.

14040

+When embedding Python, the :c:func:`initspam` function is not called

14041

+automatically unless there's an entry in the :c:data:`_PyImport_Inittab` table.

14042

The easiest way to handle this is to statically initialize your

14043

-statically-linked modules by directly calling :cfunc:`initspam` after the call

14044

-to :cfunc:`Py_Initialize`::

14045

+statically-linked modules by directly calling :c:func:`initspam` after the call

14046

+to :c:func:`Py_Initialize`::

14047

14048

int

14049

main(int argc, char *argv[])

14050

@@ -378,12 +378,12 @@

14051

.. note::

14052

14053

Removing entries from ``sys.modules`` or importing compiled modules into

14054

- multiple interpreters within a process (or following a :cfunc:`fork` without an

14055

- intervening :cfunc:`exec`) can create problems for some extension modules.

14056

+ multiple interpreters within a process (or following a :c:func:`fork` without an

14057

+ intervening :c:func:`exec`) can create problems for some extension modules.

14058

Extension module authors should exercise caution when initializing internal data

14059

structures. Note also that the :func:`reload` function can be used with

14060

extension modules, and will call the module initialization function

14061

- (:cfunc:`initspam` in the example), but will not load the module again if it was

14062

+ (:c:func:`initspam` in the example), but will not load the module again if it was

14063

loaded from a dynamically loadable object file (:file:`.so` on Unix,

14064

:file:`.dll` on Windows).

14065

14066

@@ -447,7 +447,7 @@

14067

Calling a Python function is easy. First, the Python program must somehow pass

14068

you the Python function object. You should provide a function (or some other

14069

interface) to do this. When this function is called, save a pointer to the

14070

-Python function object (be careful to :cfunc:`Py_INCREF` it!) in a global

14071

+Python function object (be careful to :c:func:`Py_INCREF` it!) in a global

14072

variable --- or wherever you see fit. For example, the following function might

14073

be part of a module definition::

14074

14075

@@ -476,10 +476,10 @@

14076

14077

This function must be registered with the interpreter using the

14078

:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The

14079

-:cfunc:`PyArg_ParseTuple` function and its arguments are documented in section

14080

+:c:func:`PyArg_ParseTuple` function and its arguments are documented in section

14081

:ref:`parsetuple`.

14082

14083

-The macros :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF` increment/decrement the

14084

+The macros :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` increment/decrement the

14085

reference count of an object and are safe in the presence of *NULL* pointers

14086

(but note that *temp* will not be *NULL* in this context). More info on them

14087

in section :ref:`refcounts`.

14088

@@ -487,12 +487,12 @@

14089

.. index:: single: PyObject_CallObject()

14090

14091

Later, when it is time to call the function, you call the C function

14092

-:cfunc:`PyObject_CallObject`. This function has two arguments, both pointers to

14093

+:c:func:`PyObject_CallObject`. This function has two arguments, both pointers to

14094

arbitrary Python objects: the Python function, and the argument list. The

14095

argument list must always be a tuple object, whose length is the number of

14096

arguments. To call the Python function with no arguments, pass in NULL, or

14097

an empty tuple; to call it with one argument, pass a singleton tuple.

14098

-:cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero

14099

+:c:func:`Py_BuildValue` returns a tuple when its format string consists of zero

14100

or more format codes between parentheses. For example::

14101

14102

int arg;

14103

@@ -506,25 +506,25 @@

14104

result = PyObject_CallObject(my_callback, arglist);

14105

Py_DECREF(arglist);

14106

14107

-:cfunc:`PyObject_CallObject` returns a Python object pointer: this is the return

14108

-value of the Python function. :cfunc:`PyObject_CallObject` is

14109

+:c:func:`PyObject_CallObject` returns a Python object pointer: this is the return

14110

+value of the Python function. :c:func:`PyObject_CallObject` is

14111

"reference-count-neutral" with respect to its arguments. In the example a new

14112

-tuple was created to serve as the argument list, which is :cfunc:`Py_DECREF`\

14113

+tuple was created to serve as the argument list, which is :c:func:`Py_DECREF`\

14114

-ed immediately after the call.

14115

14116

-The return value of :cfunc:`PyObject_CallObject` is "new": either it is a brand

14117

+The return value of :c:func:`PyObject_CallObject` is "new": either it is a brand

14118

new object, or it is an existing object whose reference count has been

14119

incremented. So, unless you want to save it in a global variable, you should

14120

-somehow :cfunc:`Py_DECREF` the result, even (especially!) if you are not

14121

+somehow :c:func:`Py_DECREF` the result, even (especially!) if you are not

14122

interested in its value.

14123

14124

Before you do this, however, it is important to check that the return value

14125

isn't *NULL*. If it is, the Python function terminated by raising an exception.

14126

-If the C code that called :cfunc:`PyObject_CallObject` is called from Python, it

14127

+If the C code that called :c:func:`PyObject_CallObject` is called from Python, it

14128

should now return an error indication to its Python caller, so the interpreter

14129

can print a stack trace, or the calling Python code can handle the exception.

14130

If this is not possible or desirable, the exception should be cleared by calling

14131

-:cfunc:`PyErr_Clear`. For example::

14132

+:c:func:`PyErr_Clear`. For example::

14133

14134

if (result == NULL)

14135

return NULL; /* Pass error back */

14136

@@ -532,12 +532,12 @@

14137

Py_DECREF(result);

14138

14139

Depending on the desired interface to the Python callback function, you may also

14140

-have to provide an argument list to :cfunc:`PyObject_CallObject`. In some cases

14141

+have to provide an argument list to :c:func:`PyObject_CallObject`. In some cases

14142

the argument list is also provided by the Python program, through the same

14143

interface that specified the callback function. It can then be saved and used

14144

in the same manner as the function object. In other cases, you may have to

14145

construct a new tuple to pass as the argument list. The simplest way to do this

14146

-is to call :cfunc:`Py_BuildValue`. For example, if you want to pass an integral

14147

+is to call :c:func:`Py_BuildValue`. For example, if you want to pass an integral

14148

event code, you might use the following code::

14149

14150

PyObject *arglist;

14151

@@ -552,11 +552,11 @@

14152

14153

Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before

14154

the error check! Also note that strictly speaking this code is not complete:

14155

-:cfunc:`Py_BuildValue` may run out of memory, and this should be checked.

14156

+:c:func:`Py_BuildValue` may run out of memory, and this should be checked.

14157

14158

You may also call a function with keyword arguments by using

14159

-:cfunc:`PyObject_Call`, which supports arguments and keyword arguments. As in

14160

-the above example, we use :cfunc:`Py_BuildValue` to construct the dictionary. ::

14161

+:c:func:`PyObject_Call`, which supports arguments and keyword arguments. As in

14162

+the above example, we use :c:func:`Py_BuildValue` to construct the dictionary. ::

14163

14164

PyObject *dict;

14165

...

14166

@@ -576,7 +576,7 @@

14167

14168

.. index:: single: PyArg_ParseTuple()

14169

14170

-The :cfunc:`PyArg_ParseTuple` function is declared as follows::

14171

+The :c:func:`PyArg_ParseTuple` function is declared as follows::

14172

14173

int PyArg_ParseTuple(PyObject *arg, char *format, ...);

14174

14175

@@ -586,7 +586,7 @@

14176

Manual. The remaining arguments must be addresses of variables whose type is

14177

determined by the format string.

14178

14179

-Note that while :cfunc:`PyArg_ParseTuple` checks that the Python arguments have

14180

+Note that while :c:func:`PyArg_ParseTuple` checks that the Python arguments have

14181

the required types, it cannot check the validity of the addresses of C variables

14182

passed to the call: if you make mistakes there, your code will probably crash or

14183

at least overwrite random bits in memory. So be careful!

14184

@@ -663,17 +663,17 @@

14185

14186

.. index:: single: PyArg_ParseTupleAndKeywords()

14187

14188

-The :cfunc:`PyArg_ParseTupleAndKeywords` function is declared as follows::

14189

+The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::

14190

14191

int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,

14192

char *format, char *kwlist[], ...);

14193

14194

The *arg* and *format* parameters are identical to those of the

14195

-:cfunc:`PyArg_ParseTuple` function. The *kwdict* parameter is the dictionary of

14196

+:c:func:`PyArg_ParseTuple` function. The *kwdict* parameter is the dictionary of

14197

keywords received as the third parameter from the Python runtime. The *kwlist*

14198

parameter is a *NULL*-terminated list of strings which identify the parameters;

14199

the names are matched with the type information from *format* from left to

14200

-right. On success, :cfunc:`PyArg_ParseTupleAndKeywords` returns true, otherwise

14201

+right. On success, :c:func:`PyArg_ParseTupleAndKeywords` returns true, otherwise

14202

it returns false and raises an appropriate exception.

14203

14204

.. note::

14205

@@ -737,19 +737,19 @@

14206

Building Arbitrary Values

14207

=========================

14208

14209

-This function is the counterpart to :cfunc:`PyArg_ParseTuple`. It is declared

14210

+This function is the counterpart to :c:func:`PyArg_ParseTuple`. It is declared

14211

as follows::

14212

14213

PyObject *Py_BuildValue(char *format, ...);

14214

14215

It recognizes a set of format units similar to the ones recognized by

14216

-:cfunc:`PyArg_ParseTuple`, but the arguments (which are input to the function,

14217

+:c:func:`PyArg_ParseTuple`, but the arguments (which are input to the function,

14218

not output) must not be pointers, just values. It returns a new Python object,

14219

suitable for returning from a C function called from Python.

14220

14221

-One difference with :cfunc:`PyArg_ParseTuple`: while the latter requires its

14222

+One difference with :c:func:`PyArg_ParseTuple`: while the latter requires its

14223

first argument to be a tuple (since Python argument lists are always represented

14224

-as tuples internally), :cfunc:`Py_BuildValue` does not always build a tuple. It

14225

+as tuples internally), :c:func:`Py_BuildValue` does not always build a tuple. It

14226

builds a tuple only if its format string contains two or more format units. If

14227

the format string is empty, it returns ``None``; if it contains exactly one

14228

format unit, it returns whatever object is described by that format unit. To

14229

@@ -781,18 +781,18 @@

14230

14231

In languages like C or C++, the programmer is responsible for dynamic allocation

14232

and deallocation of memory on the heap. In C, this is done using the functions

14233

-:cfunc:`malloc` and :cfunc:`free`. In C++, the operators ``new`` and

14234

+:c:func:`malloc` and :c:func:`free`. In C++, the operators ``new`` and

14235

``delete`` are used with essentially the same meaning and we'll restrict

14236

the following discussion to the C case.

14237

14238

-Every block of memory allocated with :cfunc:`malloc` should eventually be

14239

-returned to the pool of available memory by exactly one call to :cfunc:`free`.

14240

-It is important to call :cfunc:`free` at the right time. If a block's address

14241

-is forgotten but :cfunc:`free` is not called for it, the memory it occupies

14242

+Every block of memory allocated with :c:func:`malloc` should eventually be

14243

+returned to the pool of available memory by exactly one call to :c:func:`free`.

14244

+It is important to call :c:func:`free` at the right time. If a block's address

14245

+is forgotten but :c:func:`free` is not called for it, the memory it occupies

14246

cannot be reused until the program terminates. This is called a :dfn:`memory

14247

-leak`. On the other hand, if a program calls :cfunc:`free` for a block and then

14248

+leak`. On the other hand, if a program calls :c:func:`free` for a block and then

14249

continues to use the block, it creates a conflict with re-use of the block

14250

-through another :cfunc:`malloc` call. This is called :dfn:`using freed memory`.

14251

+through another :c:func:`malloc` call. This is called :dfn:`using freed memory`.

14252

It has the same bad consequences as referencing uninitialized data --- core

14253

dumps, wrong results, mysterious crashes.

14254

14255

@@ -809,7 +809,7 @@

14256

important to prevent leaks from happening by having a coding convention or

14257

strategy that minimizes this kind of errors.

14258

14259

-Since Python makes heavy use of :cfunc:`malloc` and :cfunc:`free`, it needs a

14260

+Since Python makes heavy use of :c:func:`malloc` and :c:func:`free`, it needs a

14261

strategy to avoid memory leaks as well as the use of freed memory. The chosen

14262

method is called :dfn:`reference counting`. The principle is simple: every

14263

object contains a counter, which is incremented when a reference to the object

14264

@@ -821,11 +821,11 @@

14265

(Sometimes, reference counting is also referred to as a garbage collection

14266

strategy, hence my use of "automatic" to distinguish the two.) The big

14267

advantage of automatic garbage collection is that the user doesn't need to call

14268

-:cfunc:`free` explicitly. (Another claimed advantage is an improvement in speed

14269

+:c:func:`free` explicitly. (Another claimed advantage is an improvement in speed

14270

or memory usage --- this is no hard fact however.) The disadvantage is that for

14271

C, there is no truly portable automatic garbage collector, while reference

14272

-counting can be implemented portably (as long as the functions :cfunc:`malloc`

14273

-and :cfunc:`free` are available --- which the C Standard guarantees). Maybe some

14274

+counting can be implemented portably (as long as the functions :c:func:`malloc`

14275

+and :c:func:`free` are available --- which the C Standard guarantees). Maybe some

14276

day a sufficiently portable automatic garbage collector will be available for C.

14277

Until then, we'll have to live with reference counts.

14278

14279

@@ -861,9 +861,9 @@

14280

----------------------------

14281

14282

There are two macros, ``Py_INCREF(x)`` and ``Py_DECREF(x)``, which handle the

14283

-incrementing and decrementing of the reference count. :cfunc:`Py_DECREF` also

14284

+incrementing and decrementing of the reference count. :c:func:`Py_DECREF` also

14285

frees the object when the count reaches zero. For flexibility, it doesn't call

14286

-:cfunc:`free` directly --- rather, it makes a call through a function pointer in

14287

+:c:func:`free` directly --- rather, it makes a call through a function pointer in

14288

the object's :dfn:`type object`. For this purpose (and others), every object

14289

also contains a pointer to its type object.

14290

14291

@@ -871,13 +871,13 @@

14292

Let's first introduce some terms. Nobody "owns" an object; however, you can

14293

:dfn:`own a reference` to an object. An object's reference count is now defined

14294

as the number of owned references to it. The owner of a reference is

14295

-responsible for calling :cfunc:`Py_DECREF` when the reference is no longer

14296

+responsible for calling :c:func:`Py_DECREF` when the reference is no longer

14297

needed. Ownership of a reference can be transferred. There are three ways to

14298

-dispose of an owned reference: pass it on, store it, or call :cfunc:`Py_DECREF`.

14299

+dispose of an owned reference: pass it on, store it, or call :c:func:`Py_DECREF`.

14300

Forgetting to dispose of an owned reference creates a memory leak.

14301

14302

It is also possible to :dfn:`borrow` [#]_ a reference to an object. The

14303

-borrower of a reference should not call :cfunc:`Py_DECREF`. The borrower must

14304

+borrower of a reference should not call :c:func:`Py_DECREF`. The borrower must

14305

not hold on to the object longer than the owner from which it was borrowed.

14306

Using a borrowed reference after the owner has disposed of it risks using freed

14307

memory and should be avoided completely. [#]_

14308

@@ -891,7 +891,7 @@

14309

disposed of it.

14310

14311

A borrowed reference can be changed into an owned reference by calling

14312

-:cfunc:`Py_INCREF`. This does not affect the status of the owner from which the

14313

+:c:func:`Py_INCREF`. This does not affect the status of the owner from which the

14314

reference was borrowed --- it creates a new owned reference, and gives full

14315

owner responsibilities (the new owner must dispose of the reference properly, as

14316

well as the previous owner).

14317

@@ -908,36 +908,36 @@

14318

14319

Most functions that return a reference to an object pass on ownership with the

14320

reference. In particular, all functions whose function it is to create a new

14321

-object, such as :cfunc:`PyInt_FromLong` and :cfunc:`Py_BuildValue`, pass

14322

+object, such as :c:func:`PyInt_FromLong` and :c:func:`Py_BuildValue`, pass

14323

ownership to the receiver. Even if the object is not actually new, you still

14324

receive ownership of a new reference to that object. For instance,

14325

-:cfunc:`PyInt_FromLong` maintains a cache of popular values and can return a

14326

+:c:func:`PyInt_FromLong` maintains a cache of popular values and can return a

14327

reference to a cached item.

14328

14329

Many functions that extract objects from other objects also transfer ownership

14330

-with the reference, for instance :cfunc:`PyObject_GetAttrString`. The picture

14331

+with the reference, for instance :c:func:`PyObject_GetAttrString`. The picture

14332

is less clear, here, however, since a few common routines are exceptions:

14333

-:cfunc:`PyTuple_GetItem`, :cfunc:`PyList_GetItem`, :cfunc:`PyDict_GetItem`, and

14334

-:cfunc:`PyDict_GetItemString` all return references that you borrow from the

14335

+:c:func:`PyTuple_GetItem`, :c:func:`PyList_GetItem`, :c:func:`PyDict_GetItem`, and

14336

+:c:func:`PyDict_GetItemString` all return references that you borrow from the

14337

tuple, list or dictionary.

14338

14339

-The function :cfunc:`PyImport_AddModule` also returns a borrowed reference, even

14340

+The function :c:func:`PyImport_AddModule` also returns a borrowed reference, even

14341

though it may actually create the object it returns: this is possible because an

14342

owned reference to the object is stored in ``sys.modules``.

14343

14344

When you pass an object reference into another function, in general, the

14345

function borrows the reference from you --- if it needs to store it, it will use

14346

-:cfunc:`Py_INCREF` to become an independent owner. There are exactly two

14347

-important exceptions to this rule: :cfunc:`PyTuple_SetItem` and

14348

-:cfunc:`PyList_SetItem`. These functions take over ownership of the item passed

14349

-to them --- even if they fail! (Note that :cfunc:`PyDict_SetItem` and friends

14350

+:c:func:`Py_INCREF` to become an independent owner. There are exactly two

14351

+important exceptions to this rule: :c:func:`PyTuple_SetItem` and

14352

+:c:func:`PyList_SetItem`. These functions take over ownership of the item passed

14353

+to them --- even if they fail! (Note that :c:func:`PyDict_SetItem` and friends

14354

don't take over ownership --- they are "normal.")

14355

14356

When a C function is called from Python, it borrows references to its arguments

14357

from the caller. The caller owns a reference to the object, so the borrowed

14358

reference's lifetime is guaranteed until the function returns. Only when such a

14359

borrowed reference must be stored or passed on, it must be turned into an owned

14360

-reference by calling :cfunc:`Py_INCREF`.

14361

+reference by calling :c:func:`Py_INCREF`.

14362

14363

The object reference returned from a C function that is called from Python must

14364

be an owned reference --- ownership is transferred from the function to its

14365

@@ -953,7 +953,7 @@

14366

can lead to problems. These all have to do with implicit invocations of the

14367

interpreter, which can cause the owner of a reference to dispose of it.

14368

14369

-The first and most important case to know about is using :cfunc:`Py_DECREF` on

14370

+The first and most important case to know about is using :c:func:`Py_DECREF` on

14371

an unrelated object while borrowing a reference to a list item. For instance::

14372

14373

void

14374

@@ -969,7 +969,7 @@

14375

``list[1]`` with the value ``0``, and finally prints the borrowed reference.

14376

Looks harmless, right? But it's not!

14377

14378

-Let's follow the control flow into :cfunc:`PyList_SetItem`. The list owns

14379

+Let's follow the control flow into :c:func:`PyList_SetItem`. The list owns

14380

references to all its items, so when item 1 is replaced, it has to dispose of

14381

the original item 1. Now let's suppose the original item 1 was an instance of a

14382

user-defined class, and let's further suppose that the class defined a

14383

@@ -978,8 +978,8 @@

14384

14385

Since it is written in Python, the :meth:`__del__` method can execute arbitrary

14386

Python code. Could it perhaps do something to invalidate the reference to

14387

-``item`` in :cfunc:`bug`? You bet! Assuming that the list passed into

14388

-:cfunc:`bug` is accessible to the :meth:`__del__` method, it could execute a

14389

+``item`` in :c:func:`bug`? You bet! Assuming that the list passed into

14390

+:c:func:`bug` is accessible to the :meth:`__del__` method, it could execute a

14391

statement to the effect of ``del list[0]``, and assuming this was the last

14392

reference to that object, it would free the memory associated with it, thereby

14393

invalidating ``item``.

14394

@@ -1006,8 +1006,8 @@

14395

threads. Normally, multiple threads in the Python interpreter can't get in each

14396

other's way, because there is a global lock protecting Python's entire object

14397

space. However, it is possible to temporarily release this lock using the macro

14398

-:cmacro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it using

14399

-:cmacro:`Py_END_ALLOW_THREADS`. This is common around blocking I/O calls, to

14400

+:c:macro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it using

14401

+:c:macro:`Py_END_ALLOW_THREADS`. This is common around blocking I/O calls, to

14402

let other threads use the processor while waiting for the I/O to complete.

14403

Obviously, the following function has the same problem as the previous one::

14404

14405

@@ -1036,11 +1036,11 @@

14406

redundant tests and the code would run more slowly.

14407

14408

It is better to test for *NULL* only at the "source:" when a pointer that may be

14409

-*NULL* is received, for example, from :cfunc:`malloc` or from a function that

14410

+*NULL* is received, for example, from :c:func:`malloc` or from a function that

14411

may raise an exception.

14412

14413

-The macros :cfunc:`Py_INCREF` and :cfunc:`Py_DECREF` do not check for *NULL*

14414

-pointers --- however, their variants :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF`

14415

+The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for *NULL*

14416

+pointers --- however, their variants :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF`

14417

do.

14418

14419

The macros for checking for a particular object type (``Pytype_Check()``) don't

14420

@@ -1114,7 +1114,7 @@

14421

14422

Python provides a special mechanism to pass C-level information (pointers) from

14423

one extension module to another one: Capsules. A Capsule is a Python data type

14424

-which stores a pointer (:ctype:`void \*`). Capsules can only be created and

14425

+which stores a pointer (:c:type:`void \*`). Capsules can only be created and

14426

accessed via their C API, but they can be passed around like any other Python

14427

object. In particular, they can be assigned to a name in an extension module's

14428

namespace. Other extension modules can then import this module, retrieve the

14429

@@ -1127,8 +1127,8 @@

14430

different ways between the module providing the code and the client modules.

14431

14432

Whichever method you choose, it's important to name your Capsules properly.

14433

-The function :cfunc:`PyCapsule_New` takes a name parameter

14434

-(:ctype:`const char \*`); you're permitted to pass in a *NULL* name, but

14435

+The function :c:func:`PyCapsule_New` takes a name parameter

14436

+(:c:type:`const char \*`); you're permitted to pass in a *NULL* name, but

14437

we strongly encourage you to specify a name. Properly named Capsules provide

14438

a degree of runtime type-safety; there is no feasible way to tell one unnamed

14439

Capsule from another.

14440

@@ -1138,7 +1138,7 @@

14441

14442

modulename.attributename

14443

14444

-The convenience function :cfunc:`PyCapsule_Import` makes it easy to

14445

+The convenience function :c:func:`PyCapsule_Import` makes it easy to

14446

load a C API provided via a Capsule, but only if the Capsule's name

14447

matches this convention. This behavior gives C API users a high degree

14448

of certainty that the Capsule they load contains the correct C API.

14449

@@ -1146,19 +1146,19 @@

14450

The following example demonstrates an approach that puts most of the burden on

14451

the writer of the exporting module, which is appropriate for commonly used

14452

library modules. It stores all C API pointers (just one in the example!) in an

14453

-array of :ctype:`void` pointers which becomes the value of a Capsule. The header

14454

+array of :c:type:`void` pointers which becomes the value of a Capsule. The header

14455

file corresponding to the module provides a macro that takes care of importing

14456

the module and retrieving its C API pointers; client modules only have to call

14457

this macro before accessing the C API.

14458

14459

The exporting module is a modification of the :mod:`spam` module from section

14460

:ref:`extending-simpleexample`. The function :func:`spam.system` does not call

14461

-the C library function :cfunc:`system` directly, but a function

14462

-:cfunc:`PySpam_System`, which would of course do something more complicated in

14463

+the C library function :c:func:`system` directly, but a function

14464

+:c:func:`PySpam_System`, which would of course do something more complicated in

14465

reality (such as adding "spam" to every command). This function

14466

-:cfunc:`PySpam_System` is also exported to other extension modules.

14467

+:c:func:`PySpam_System` is also exported to other extension modules.

14468

14469

-The function :cfunc:`PySpam_System` is a plain C function, declared

14470

+The function :c:func:`PySpam_System` is a plain C function, declared

14471

``static`` like everything else::

14472

14473

static int

14474

@@ -1167,7 +1167,7 @@

14475

return system(command);

14476

}

14477

14478

-The function :cfunc:`spam_system` is modified in a trivial way::

14479

+The function :c:func:`spam_system` is modified in a trivial way::

14480

14481

static PyObject *

14482

spam_system(PyObject *self, PyObject *args)

14483

@@ -1270,8 +1270,8 @@

14484

#endif /* !defined(Py_SPAMMODULE_H) */

14485

14486

All that a client module must do in order to have access to the function

14487

-:cfunc:`PySpam_System` is to call the function (or rather macro)

14488

-:cfunc:`import_spam` in its initialization function::

14489

+:c:func:`PySpam_System` is to call the function (or rather macro)

14490

+:c:func:`import_spam` in its initialization function::

14491

14492

PyMODINIT_FUNC

14493

initclient(void)

14494

diff -r 8527427914a2 Doc/extending/newtypes.rst

14495

--- a/Doc/extending/newtypes.rst

14496

+++ b/Doc/extending/newtypes.rst

14497

@@ -34,12 +34,11 @@

14498

==========

14499

14500

The Python runtime sees all Python objects as variables of type

14501

-:ctype:`PyObject\*`. A :ctype:`PyObject` is not a very magnificent object - it

14502

+:c:type:`PyObject\*`. A :c:type:`PyObject` is not a very magnificent object - it

14503

just contains the refcount and a pointer to the object's "type object". This is

14504

where the action is; the type object determines which (C) functions get called

14505

when, for instance, an attribute gets looked up on an object or it is multiplied

14506

-by another object. These C functions are called "type methods" to distinguish

14507

-them from things like ``[].append`` (which we call "object methods").

14508

+by another object. These C functions are called "type methods".

14509

14510

So, if you want to define a new object type, you need to create a new type

14511

object.

14512

@@ -104,7 +103,7 @@

14513

"Noddy objects", /* tp_doc */

14514

};

14515

14516

-Now if you go and look up the definition of :ctype:`PyTypeObject` in

14517

+Now if you go and look up the definition of :c:type:`PyTypeObject` in

14518

:file:`object.h` you'll see that it has many more fields that the definition

14519

above. The remaining fields will be filled with zeros by the C compiler, and

14520

it's common practice to not specify them explicitly unless you need them.

14521

@@ -120,7 +119,7 @@

14522

14523

as the type of a type object is "type", but this isn't strictly conforming C and

14524

some compilers complain. Fortunately, this member will be filled in for us by

14525

-:cfunc:`PyType_Ready`. ::

14526

+:c:func:`PyType_Ready`. ::

14527

14528

0, /* ob_size */

14529

14530

@@ -146,7 +145,7 @@

14531

sizeof(noddy_NoddyObject), /* tp_basicsize */

14532

14533

This is so that Python knows how much memory to allocate when you call

14534

-:cfunc:`PyObject_New`.

14535

+:c:func:`PyObject_New`.

14536

14537

.. note::

14538

14539

@@ -186,12 +185,12 @@

14540

For now, all we want to be able to do is to create new :class:`Noddy` objects.

14541

To enable object creation, we have to provide a :attr:`tp_new` implementation.

14542

In this case, we can just use the default implementation provided by the API

14543

-function :cfunc:`PyType_GenericNew`. We'd like to just assign this to the

14544

+function :c:func:`PyType_GenericNew`. We'd like to just assign this to the

14545

:attr:`tp_new` slot, but we can't, for portability sake, On some platforms or

14546

compilers, we can't statically initialize a structure member with a function

14547

defined in another C module, so, instead, we'll assign the :attr:`tp_new` slot

14548

in the module initialization function just before calling

14549

-:cfunc:`PyType_Ready`::

14550

+:c:func:`PyType_Ready`::

14551

14552

noddy_NoddyType.tp_new = PyType_GenericNew;

14553

if (PyType_Ready(&noddy_NoddyType) < 0)

14554

@@ -201,7 +200,7 @@

14555

for a later section!

14556

14557

Everything else in the file should be familiar, except for some code in

14558

-:cfunc:`initnoddy`::

14559

+:c:func:`initnoddy`::

14560

14561

if (PyType_Ready(&noddy_NoddyType) < 0)

14562

return;

14563

@@ -289,7 +288,7 @@

14564

(destructor)Noddy_dealloc, /*tp_dealloc*/

14565

14566

This method decrements the reference counts of the two Python attributes. We use

14567

-:cfunc:`Py_XDECREF` here because the :attr:`first` and :attr:`last` members

14568

+:c:func:`Py_XDECREF` here because the :attr:`first` and :attr:`last` members

14569

could be *NULL*. It then calls the :attr:`tp_free` member of the object's type

14570

to free the object's memory. Note that the object's type might not be

14571

:class:`NoddyType`, because the object may be an instance of a subclass.

14572

@@ -335,8 +334,8 @@

14573

the initial values of instance variables. In this case, we use the new method

14574

to make sure that the initial values of the members :attr:`first` and

14575

:attr:`last` are not *NULL*. If we didn't care whether the initial values were

14576

-*NULL*, we could have used :cfunc:`PyType_GenericNew` as our new method, as we

14577

-did before. :cfunc:`PyType_GenericNew` initializes all of the instance variable

14578

+*NULL*, we could have used :c:func:`PyType_GenericNew` as our new method, as we

14579

+did before. :c:func:`PyType_GenericNew` initializes all of the instance variable

14580

members to *NULL*.

14581

14582

The new method is a static method that is passed the type being instantiated and

14583

@@ -346,7 +345,7 @@

14584

methods. Note that if the type supports subclassing, the type passed may not be

14585

the type being defined. The new method calls the tp_alloc slot to allocate

14586

memory. We don't fill the :attr:`tp_alloc` slot ourselves. Rather

14587

-:cfunc:`PyType_Ready` fills it for us by inheriting it from our base class,

14588

+:c:func:`PyType_Ready` fills it for us by inheriting it from our base class,

14589

which is :class:`object` by default. Most types use the default allocation.

14590

14591

.. note::

14592

@@ -531,8 +530,8 @@

14593

14594

Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/

14595

14596

-We rename :cfunc:`initnoddy` to :cfunc:`initnoddy2` and update the module name

14597

-passed to :cfunc:`Py_InitModule3`.

14598

+We rename :c:func:`initnoddy` to :c:func:`initnoddy2` and update the module name

14599

+passed to :c:func:`Py_InitModule3`.

14600

14601

Finally, we update our :file:`setup.py` file to build the new module::

14602

14603

@@ -598,7 +597,7 @@

14604

deleted. In our setter, we raise an error if the attribute is deleted or if the

14605

attribute value is not a string.

14606

14607

-We create an array of :ctype:`PyGetSetDef` structures::

14608

+We create an array of :c:type:`PyGetSetDef` structures::

14609

14610

static PyGetSetDef Noddy_getseters[] = {

14611

{"first",

14612

@@ -618,7 +617,7 @@

14613

14614

to register our attribute getters and setters.

14615

14616

-The last item in a :ctype:`PyGetSetDef` structure is the closure mentioned

14617

+The last item in a :c:type:`PyGetSetDef` structure is the closure mentioned

14618

above. In this case, we aren't using the closure, so we just pass *NULL*.

14619

14620

We also remove the member definitions for these attributes::

14621

@@ -663,8 +662,8 @@

14622

14623

With these changes, we can assure that the :attr:`first` and :attr:`last`

14624

members are never *NULL* so we can remove checks for *NULL* values in almost all

14625

-cases. This means that most of the :cfunc:`Py_XDECREF` calls can be converted to

14626

-:cfunc:`Py_DECREF` calls. The only place we can't change these calls is in the

14627

+cases. This means that most of the :c:func:`Py_XDECREF` calls can be converted to

14628

+:c:func:`Py_DECREF` calls. The only place we can't change these calls is in the

14629

deallocator, where there is the possibility that the initialization of these

14630

members failed in the constructor.

14631

14632

@@ -729,13 +728,13 @@

14633

}

14634

14635

For each subobject that can participate in cycles, we need to call the

14636

-:cfunc:`visit` function, which is passed to the traversal method. The

14637

-:cfunc:`visit` function takes as arguments the subobject and the extra argument

14638

+:c:func:`visit` function, which is passed to the traversal method. The

14639

+:c:func:`visit` function takes as arguments the subobject and the extra argument

14640

*arg* passed to the traversal method. It returns an integer value that must be

14641

returned if it is non-zero.

14642

14643

-Python 2.4 and higher provide a :cfunc:`Py_VISIT` macro that automates calling

14644

-visit functions. With :cfunc:`Py_VISIT`, :cfunc:`Noddy_traverse` can be

14645

+Python 2.4 and higher provide a :c:func:`Py_VISIT` macro that automates calling

14646

+visit functions. With :c:func:`Py_VISIT`, :c:func:`Noddy_traverse` can be

14647

simplified::

14648

14649

static int

14650

@@ -749,7 +748,7 @@

14651

.. note::

14652

14653

Note that the :attr:`tp_traverse` implementation must name its arguments exactly

14654

- *visit* and *arg* in order to use :cfunc:`Py_VISIT`. This is to encourage

14655

+ *visit* and *arg* in order to use :c:func:`Py_VISIT`. This is to encourage

14656

uniformity across these boring implementations.

14657

14658

We also need to provide a method for clearing any subobjects that can

14659

@@ -779,19 +778,19 @@

14660

self->ob_type->tp_free((PyObject*)self);

14661

}

14662

14663

-Notice the use of a temporary variable in :cfunc:`Noddy_clear`. We use the

14664

+Notice the use of a temporary variable in :c:func:`Noddy_clear`. We use the

14665

temporary variable so that we can set each member to *NULL* before decrementing

14666

its reference count. We do this because, as was discussed earlier, if the

14667

reference count drops to zero, we might cause code to run that calls back into

14668

the object. In addition, because we now support garbage collection, we also

14669

have to worry about code being run that triggers garbage collection. If garbage

14670

collection is run, our :attr:`tp_traverse` handler could get called. We can't

14671

-take a chance of having :cfunc:`Noddy_traverse` called when a member's reference

14672

+take a chance of having :c:func:`Noddy_traverse` called when a member's reference

14673

count has dropped to zero and its value hasn't been set to *NULL*.

14674

14675

-Python 2.4 and higher provide a :cfunc:`Py_CLEAR` that automates the careful

14676

-decrementing of reference counts. With :cfunc:`Py_CLEAR`, the

14677

-:cfunc:`Noddy_clear` function can be simplified::

14678

+Python 2.4 and higher provide a :c:func:`Py_CLEAR` that automates the careful

14679

+decrementing of reference counts. With :c:func:`Py_CLEAR`, the

14680

+:c:func:`Noddy_clear` function can be simplified::

14681

14682

static int

14683

Noddy_clear(Noddy *self)

14684

@@ -846,7 +845,7 @@

14685

14686

The primary difference for derived type objects is that the base type's object

14687

structure must be the first value. The base type will already include the

14688

-:cfunc:`PyObject_HEAD` at the beginning of its structure.

14689

+:c:func:`PyObject_HEAD` at the beginning of its structure.

14690

14691

When a Python object is a :class:`Shoddy` instance, its *PyObject\** pointer can

14692

be safely cast to both *PyListObject\** and *Shoddy\**. ::

14693

@@ -868,10 +867,10 @@

14694

memory for the object with :attr:`tp_alloc`, that will be handled by the base

14695

class when calling its :attr:`tp_new`.

14696

14697

-When filling out the :cfunc:`PyTypeObject` for the :class:`Shoddy` type, you see

14698

-a slot for :cfunc:`tp_base`. Due to cross platform compiler issues, you can't

14699

-fill that field directly with the :cfunc:`PyList_Type`; it can be done later in

14700

-the module's :cfunc:`init` function. ::

14701

+When filling out the :c:func:`PyTypeObject` for the :class:`Shoddy` type, you see

14702

+a slot for :c:func:`tp_base`. Due to cross platform compiler issues, you can't

14703

+fill that field directly with the :c:func:`PyList_Type`; it can be done later in

14704

+the module's :c:func:`init` function. ::

14705

14706

PyMODINIT_FUNC

14707

initshoddy(void)

14708

@@ -890,12 +889,12 @@

14709

PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);

14710

}

14711

14712

-Before calling :cfunc:`PyType_Ready`, the type structure must have the

14713

+Before calling :c:func:`PyType_Ready`, the type structure must have the

14714

:attr:`tp_base` slot filled in. When we are deriving a new type, it is not

14715

-necessary to fill out the :attr:`tp_alloc` slot with :cfunc:`PyType_GenericNew`

14716

+necessary to fill out the :attr:`tp_alloc` slot with :c:func:`PyType_GenericNew`

14717

-- the allocate function from the base type will be inherited.

14718

14719

-After that, calling :cfunc:`PyType_Ready` and adding the type object to the

14720

+After that, calling :c:func:`PyType_Ready` and adding the type object to the

14721

module is the same as with the basic :class:`Noddy` examples.

14722

14723

14724

@@ -907,7 +906,7 @@

14725

This section aims to give a quick fly-by on the various type methods you can

14726

implement and what they do.

14727

14728

-Here is the definition of :ctype:`PyTypeObject`, with some fields only used in

14729

+Here is the definition of :c:type:`PyTypeObject`, with some fields only used in

14730

debug builds omitted:

14731

14732

.. literalinclude:: ../includes/typestruct.h

14733

@@ -985,8 +984,8 @@

14734

executed may detect that an exception has been set. This can lead to misleading

14735

errors from the interpreter. The proper way to protect against this is to save

14736

a pending exception before performing the unsafe action, and restoring it when

14737

-done. This can be done using the :cfunc:`PyErr_Fetch` and

14738

-:cfunc:`PyErr_Restore` functions::

14739

+done. This can be done using the :c:func:`PyErr_Fetch` and

14740

+:c:func:`PyErr_Restore` functions::

14741

14742

static void

14743

my_dealloc(PyObject *obj)

14744

@@ -1027,7 +1026,7 @@

14745

object: the :func:`repr` function (or equivalent back-tick syntax), the

14746

:func:`str` function, and the :keyword:`print` statement. For most objects, the

14747

:keyword:`print` statement is equivalent to the :func:`str` function, but it is

14748

-possible to special-case printing to a :ctype:`FILE\*` if necessary; this should

14749

+possible to special-case printing to a :c:type:`FILE\*` if necessary; this should

14750

only be done if efficiency is identified as a problem and profiling suggests

14751

that creating a temporary string object to be written to a file is too

14752

expensive.

14753

@@ -1111,8 +1110,8 @@

14754

14755

Python supports two pairs of attribute handlers; a type that supports attributes

14756

only needs to implement the functions for one pair. The difference is that one

14757

-pair takes the name of the attribute as a :ctype:`char\*`, while the other

14758

-accepts a :ctype:`PyObject\*`. Each type can use whichever pair makes more

14759

+pair takes the name of the attribute as a :c:type:`char\*`, while the other

14760

+accepts a :c:type:`PyObject\*`. Each type can use whichever pair makes more

14761

sense for the implementation's convenience. ::

14762

14763

getattrfunc tp_getattr; /* char * version */

14764

@@ -1123,7 +1122,7 @@

14765

14766

If accessing attributes of an object is always a simple operation (this will be

14767

explained shortly), there are generic implementations which can be used to

14768

-provide the :ctype:`PyObject\*` version of the attribute management functions.

14769

+provide the :c:type:`PyObject\*` version of the attribute management functions.

14770

The actual need for type-specific attribute handlers almost completely

14771

disappeared starting with Python 2.2, though there are many examples which have

14772

not been updated to use some of the new generic mechanism that is available.

14773

@@ -1139,7 +1138,7 @@

14774

Most extension types only use *simple* attributes. So, what makes the

14775

attributes simple? There are only a couple of conditions that must be met:

14776

14777

-#. The name of the attributes must be known when :cfunc:`PyType_Ready` is

14778

+#. The name of the attributes must be known when :c:func:`PyType_Ready` is

14779

called.

14780

14781

#. No special processing is needed to record that an attribute was looked up or

14782

@@ -1148,7 +1147,7 @@

14783

Note that this list does not place any restrictions on the values of the

14784

attributes, when the values are computed, or how relevant data is stored.

14785

14786

-When :cfunc:`PyType_Ready` is called, it uses three tables referenced by the

14787

+When :c:func:`PyType_Ready` is called, it uses three tables referenced by the

14788

type object to create :term:`descriptor`\s which are placed in the dictionary of the

14789

type object. Each descriptor controls access to one attribute of the instance

14790

object. Each of the tables is optional; if all three are *NULL*, instances of

14791

@@ -1163,7 +1162,7 @@

14792

struct PyGetSetDef *tp_getset;

14793

14794

If :attr:`tp_methods` is not *NULL*, it must refer to an array of

14795

-:ctype:`PyMethodDef` structures. Each entry in the table is an instance of this

14796

+:c:type:`PyMethodDef` structures. Each entry in the table is an instance of this

14797

structure::

14798

14799

typedef struct PyMethodDef {

14800

@@ -1248,9 +1247,9 @@

14801

Type-specific Attribute Management

14802

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

14803

14804

-For simplicity, only the :ctype:`char\*` version will be demonstrated here; the

14805

-type of the name parameter is the only difference between the :ctype:`char\*`

14806

-and :ctype:`PyObject\*` flavors of the interface. This example effectively does

14807

+For simplicity, only the :c:type:`char\*` version will be demonstrated here; the

14808

+type of the name parameter is the only difference between the :c:type:`char\*`

14809

+and :c:type:`PyObject\*` flavors of the interface. This example effectively does

14810

the same thing as the generic example above, but does not use the generic

14811

support added in Python 2.2. The value in showing this is two-fold: it

14812

demonstrates how basic attribute management can be done in a way that is

14813

@@ -1263,7 +1262,7 @@

14814

method of a class would be called.

14815

14816

A likely way to handle this is (1) to implement a set of functions (such as

14817

-:cfunc:`newdatatype_getSize` and :cfunc:`newdatatype_setSize` in the example

14818

+:c:func:`newdatatype_getSize` and :c:func:`newdatatype_setSize` in the example

14819

below), (2) provide a method table listing these functions, and (3) provide a

14820

getattr function that returns the result of a lookup in that table. The method

14821

table uses the same structure as the :attr:`tp_methods` field of the type

14822

@@ -1309,7 +1308,7 @@

14823

The :attr:`tp_compare` handler is called when comparisons are needed and the

14824

object does not implement the specific rich comparison method which matches the

14825

requested comparison. (It is always used if defined and the

14826

-:cfunc:`PyObject_Compare` or :cfunc:`PyObject_Cmp` functions are used, or if

14827

+:c:func:`PyObject_Compare` or :c:func:`PyObject_Cmp` functions are used, or if

14828

:func:`cmp` is used from Python.) It is analogous to the :meth:`__cmp__` method.

14829

This function should return ``-1`` if *obj1* is less than *obj2*, ``0`` if they

14830

are equal, and ``1`` if *obj1* is greater than *obj2*. (It was previously

14831

@@ -1319,7 +1318,7 @@

14832

14833

A :attr:`tp_compare` handler may raise an exception. In this case it should

14834

return a negative value. The caller has to test for the exception using

14835

-:cfunc:`PyErr_Occurred`.

14836

+:c:func:`PyErr_Occurred`.

14837

14838

Here is a sample implementation::

14839

14840

@@ -1367,8 +1366,8 @@

14841

14842

If you wish your object to be able to act like a number, a sequence, or a

14843

mapping object, then you place the address of a structure that implements the C

14844

-type :ctype:`PyNumberMethods`, :ctype:`PySequenceMethods`, or

14845

-:ctype:`PyMappingMethods`, respectively. It is up to you to fill in this

14846

+type :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, or

14847

+:c:type:`PyMappingMethods`, respectively. It is up to you to fill in this

14848

structure with appropriate values. You can find examples of the use of each of

14849

these in the :file:`Objects` directory of the Python source distribution. ::

14850

14851

@@ -1400,11 +1399,11 @@

14852

the call is ``obj1('hello')``, then *arg1* is ``obj1``.

14853

14854

#. *arg2* is a tuple containing the arguments to the call. You can use

14855

- :cfunc:`PyArg_ParseTuple` to extract the arguments.

14856

+ :c:func:`PyArg_ParseTuple` to extract the arguments.

14857

14858

#. *arg3* is a dictionary of keyword arguments that were passed. If this is

14859

non-*NULL* and you support keyword arguments, use

14860

- :cfunc:`PyArg_ParseTupleAndKeywords` to extract the arguments. If you do not

14861

+ :c:func:`PyArg_ParseTupleAndKeywords` to extract the arguments. If you do not

14862

want to support keyword arguments and this is non-*NULL*, raise a

14863

:exc:`TypeError` with a message saying that keyword arguments are not supported.

14864

14865

@@ -1479,7 +1478,7 @@

14866

those objects which do not benefit by weak referencing (such as numbers).

14867

14868

For an object to be weakly referencable, the extension must include a

14869

-:ctype:`PyObject\*` field in the instance structure for the use of the weak

14870

+:c:type:`PyObject\*` field in the instance structure for the use of the weak

14871

reference mechanism; it must be initialized to *NULL* by the object's

14872

constructor. It must also set the :attr:`tp_weaklistoffset` field of the

14873

corresponding type object to the offset of the field. For example, the instance

14874

@@ -1555,7 +1554,7 @@

14875

examples of the function you want to implement.

14876

14877

When you need to verify that an object is an instance of the type you are

14878

-implementing, use the :cfunc:`PyObject_TypeCheck` function. A sample of its use

14879

+implementing, use the :c:func:`PyObject_TypeCheck` function. A sample of its use

14880

might be something like the following::

14881

14882

if (! PyObject_TypeCheck(some_object, &MyType)) {

14883

diff -r 8527427914a2 Doc/extending/windows.rst

14884

--- a/Doc/extending/windows.rst

14885

+++ b/Doc/extending/windows.rst

14886

@@ -98,8 +98,8 @@

14887

it. Copy your C sources into it. Note that the module source file name does

14888

not necessarily have to match the module name, but the name of the

14889

initialization function should match the module name --- you can only import a

14890

- module :mod:`spam` if its initialization function is called :cfunc:`initspam`,

14891

- and it should call :cfunc:`Py_InitModule` with the string ``"spam"`` as its

14892

+ module :mod:`spam` if its initialization function is called :c:func:`initspam`,

14893

+ and it should call :c:func:`Py_InitModule` with the string ``"spam"`` as its

14894

first argument (use the minimal :file:`example.c` in this directory as a guide).

14895

By convention, it lives in a file called :file:`spam.c` or :file:`spammodule.c`.

14896

The output file should be called :file:`spam.pyd` (in Release mode) or

14897

@@ -263,7 +263,7 @@

14898

14899

The first command created three files: :file:`spam.obj`, :file:`spam.dll` and

14900

:file:`spam.lib`. :file:`Spam.dll` does not contain any Python functions (such

14901

-as :cfunc:`PyArg_ParseTuple`), but it does know how to find the Python code

14902

+as :c:func:`PyArg_ParseTuple`), but it does know how to find the Python code

14903

thanks to :file:`pythonXY.lib`.

14904

14905

The second command created :file:`ni.dll` (and :file:`.obj` and :file:`.lib`),

14906

diff -r 8527427914a2 Doc/faq/design.rst

14907

--- a/Doc/faq/design.rst

14908

+++ b/Doc/faq/design.rst

14909

@@ -684,7 +684,7 @@

14910

Python 2.6 adds an :mod:`abc` module that lets you define Abstract Base Classes

14911

(ABCs). You can then use :func:`isinstance` and :func:`issubclass` to check

14912

whether an instance or a class implements a particular ABC. The

14913

-:mod:`collections` modules defines a set of useful ABCs such as

14914

+:mod:`collections` module defines a set of useful ABCs such as

14915

:class:`Iterable`, :class:`Container`, and :class:`MutableMapping`.

14916

14917

For Python, many of the advantages of interface specifications can be obtained

14918

diff -r 8527427914a2 Doc/faq/extending.rst

14919

--- a/Doc/faq/extending.rst

14920

+++ b/Doc/faq/extending.rst

14921

@@ -60,41 +60,41 @@

14922

How can I execute arbitrary Python statements from C?

14923

-----------------------------------------------------

14924

14925

-The highest-level function to do this is :cfunc:`PyRun_SimpleString` which takes

14926

+The highest-level function to do this is :c:func:`PyRun_SimpleString` which takes

14927

a single string argument to be executed in the context of the module

14928

``__main__`` and returns 0 for success and -1 when an exception occurred

14929

(including ``SyntaxError``). If you want more control, use

14930

-:cfunc:`PyRun_String`; see the source for :cfunc:`PyRun_SimpleString` in

14931

+:c:func:`PyRun_String`; see the source for :c:func:`PyRun_SimpleString` in

14932

``Python/pythonrun.c``.

14933

14934

14935

How can I evaluate an arbitrary Python expression from C?

14936

---------------------------------------------------------

14937

14938

-Call the function :cfunc:`PyRun_String` from the previous question with the

14939

-start symbol :cdata:`Py_eval_input`; it parses an expression, evaluates it and

14940

+Call the function :c:func:`PyRun_String` from the previous question with the

14941

+start symbol :c:data:`Py_eval_input`; it parses an expression, evaluates it and

14942

returns its value.

14943

14944

14945

How do I extract C values from a Python object?

14946

-----------------------------------------------

14947

14948

-That depends on the object's type. If it's a tuple, :cfunc:`PyTuple_Size`

14949

-returns its length and :cfunc:`PyTuple_GetItem` returns the item at a specified

14950

-index. Lists have similar functions, :cfunc:`PyListSize` and

14951

-:cfunc:`PyList_GetItem`.

14952

+That depends on the object's type. If it's a tuple, :c:func:`PyTuple_Size`

14953

+returns its length and :c:func:`PyTuple_GetItem` returns the item at a specified

14954

+index. Lists have similar functions, :c:func:`PyListSize` and

14955

+:c:func:`PyList_GetItem`.

14956

14957

-For strings, :cfunc:`PyString_Size` returns its length and

14958

-:cfunc:`PyString_AsString` a pointer to its value. Note that Python strings may

14959

-contain null bytes so C's :cfunc:`strlen` should not be used.

14960

+For strings, :c:func:`PyString_Size` returns its length and

14961

+:c:func:`PyString_AsString` a pointer to its value. Note that Python strings may

14962

+contain null bytes so C's :c:func:`strlen` should not be used.

14963

14964

To test the type of an object, first make sure it isn't *NULL*, and then use

14965

-:cfunc:`PyString_Check`, :cfunc:`PyTuple_Check`, :cfunc:`PyList_Check`, etc.

14966

+:c:func:`PyString_Check`, :c:func:`PyTuple_Check`, :c:func:`PyList_Check`, etc.

14967

14968

There is also a high-level API to Python objects which is provided by the

14969

so-called 'abstract' interface -- read ``Include/abstract.h`` for further

14970

details. It allows interfacing with any kind of Python sequence using calls

14971

-like :cfunc:`PySequence_Length`, :cfunc:`PySequence_GetItem`, etc.) as well as

14972

+like :c:func:`PySequence_Length`, :c:func:`PySequence_GetItem`, etc.) as well as

14973

many other useful protocols.

14974

14975

14976

@@ -103,7 +103,7 @@

14977

14978

You can't. Use ``t = PyTuple_New(n)`` instead, and fill it with objects using

14979

``PyTuple_SetItem(t, i, o)`` -- note that this "eats" a reference count of

14980

-``o``, so you have to :cfunc:`Py_INCREF` it. Lists have similar functions

14981

+``o``, so you have to :c:func:`Py_INCREF` it. Lists have similar functions

14982

``PyList_New(n)`` and ``PyList_SetItem(l, i, o)``. Note that you *must* set all

14983

the tuple items to some value before you pass the tuple to Python code --

14984

``PyTuple_New(n)`` initializes them to NULL, which isn't a valid Python value.

14985

@@ -112,9 +112,9 @@

14986

How do I call an object's method from C?

14987

----------------------------------------

14988

14989

-The :cfunc:`PyObject_CallMethod` function can be used to call an arbitrary

14990

+The :c:func:`PyObject_CallMethod` function can be used to call an arbitrary

14991

method of an object. The parameters are the object, the name of the method to

14992

-call, a format string like that used with :cfunc:`Py_BuildValue`, and the

14993

+call, a format string like that used with :c:func:`Py_BuildValue`, and the

14994

argument values::

14995

14996

PyObject *

14997

@@ -122,7 +122,7 @@

14998

char *arg_format, ...);

14999

15000

This works for any object that has methods -- whether built-in or user-defined.

15001

-You are responsible for eventually :cfunc:`Py_DECREF`\ 'ing the return value.

15002

+You are responsible for eventually :c:func:`Py_DECREF`\ 'ing the return value.

15003

15004

To call, e.g., a file object's "seek" method with arguments 10, 0 (assuming the

15005

file object pointer is "f")::

15006

@@ -135,7 +135,7 @@

15007

Py_DECREF(res);

15008

}

15009

15010

-Note that since :cfunc:`PyObject_CallObject` *always* wants a tuple for the

15011

+Note that since :c:func:`PyObject_CallObject` *always* wants a tuple for the

15012

argument list, to call a function without arguments, pass "()" for the format,

15013

and to call a function with one argument, surround the argument in parentheses,

15014

e.g. "(i)".

15015

@@ -186,7 +186,7 @@

15016

15017

attr = PyObject_GetAttrString(module, "<attrname>");

15018

15019

-Calling :cfunc:`PyObject_SetAttrString` to assign to variables in the module

15020

+Calling :c:func:`PyObject_SetAttrString` to assign to variables in the module

15021

also works.

15022

15023

15024

@@ -267,16 +267,16 @@

15025

In Python you can use the :mod:`codeop` module, which approximates the parser's

15026

behavior sufficiently. IDLE uses this, for example.

15027

15028

-The easiest way to do it in C is to call :cfunc:`PyRun_InteractiveLoop` (perhaps

15029

+The easiest way to do it in C is to call :c:func:`PyRun_InteractiveLoop` (perhaps

15030

in a separate thread) and let the Python interpreter handle the input for

15031

-you. You can also set the :cfunc:`PyOS_ReadlineFunctionPointer` to point at your

15032

+you. You can also set the :c:func:`PyOS_ReadlineFunctionPointer` to point at your

15033

custom input function. See ``Modules/readline.c`` and ``Parser/myreadline.c``

15034

for more hints.

15035

15036

However sometimes you have to run the embedded Python interpreter in the same

15037

thread as your rest application and you can't allow the

15038

-:cfunc:`PyRun_InteractiveLoop` to stop while waiting for user input. The one

15039

-solution then is to call :cfunc:`PyParser_ParseString` and test for ``e.error``

15040

+:c:func:`PyRun_InteractiveLoop` to stop while waiting for user input. The one

15041

+solution then is to call :c:func:`PyParser_ParseString` and test for ``e.error``

15042

equal to ``E_EOF``, which means the input is incomplete). Here's a sample code

15043

fragment, untested, inspired by code from Alex Farber::

15044

15045

@@ -307,8 +307,8 @@

15046

}

15047

15048

Another solution is trying to compile the received string with

15049

-:cfunc:`Py_CompileString`. If it compiles without errors, try to execute the

15050

-returned code object by calling :cfunc:`PyEval_EvalCode`. Otherwise save the

15051

+:c:func:`Py_CompileString`. If it compiles without errors, try to execute the

15052

+returned code object by calling :c:func:`PyEval_EvalCode`. Otherwise save the

15053

input for later. If the compilation fails, find out if it's an error or just

15054

more input is required - by extracting the message string from the exception

15055

tuple and comparing it to the string "unexpected EOF while parsing". Here is a

15056

@@ -460,8 +460,8 @@

15057

7.x, in particular, provided a "python2" binary that is compiled with 4-byte

15058

Unicode. This only causes the link failure if the extension uses any of the

15059

``PyUnicode_*()`` functions. It is also a problem if an extension uses any of

15060

-the Unicode-related format specifiers for :cfunc:`Py_BuildValue` (or similar) or

15061

-parameter specifications for :cfunc:`PyArg_ParseTuple`.

15062

+the Unicode-related format specifiers for :c:func:`Py_BuildValue` (or similar) or

15063

+parameter specifications for :c:func:`PyArg_ParseTuple`.

15064

15065

You can check the size of the Unicode character a Python interpreter is using by

15066

checking the value of sys.maxunicode:

15067

diff -r 8527427914a2 Doc/faq/general.rst

15068

--- a/Doc/faq/general.rst

15069

+++ b/Doc/faq/general.rst

15070

@@ -157,16 +157,14 @@

15071

15072

The latest Python source distribution is always available from python.org, at

15073

http://www.python.org/download/. The latest development sources can be obtained

15074

-via anonymous Subversion at http://svn.python.org/projects/python/trunk.

15075

+via anonymous Mercurial access at http://hg.python.org/cpython.

15076

15077

The source distribution is a gzipped tar file containing the complete C source,

15078

Sphinx-formatted documentation, Python library modules, example programs, and

15079

several useful pieces of freely distributable software. The source will compile

15080

and run out of the box on most UNIX platforms.

15081

15082

-.. XXX update link once the dev faq is relocated

15083

-

15084

-Consult the `Developer FAQ <http://www.python.org/dev/faq/>`__ for more

15085

+Consult the `Developer FAQ <http://docs.python.org/devguide/faq>`__ for more

15086

information on getting the source code and compiling it.

15087

15088

15089

@@ -221,10 +219,8 @@

15090

newsgroups and on the Python home page at http://www.python.org/; an RSS feed of

15091

news is available.

15092

15093

-.. XXX update link once the dev faq is relocated

15094

-

15095

You can also access the development version of Python through Subversion. See

15096

-http://www.python.org/dev/faq/ for details.

15097

+http://docs.python.org/devguide/faq for details.

15098

15099

15100

How do I submit bug reports and patches for Python?

15101

@@ -239,10 +235,8 @@

15102

report bugs to Python, you can obtain your Roundup password through Roundup's

15103

`password reset procedure <http://bugs.python.org/user?@template=forgotten>`_.

15104

15105

-.. XXX adapt link to dev guide

15106

-

15107

For more information on how Python is developed, consult `the Python Developer's

15108

-Guide <http://python.org/dev/>`_.

15109

+Guide <http://docs.python.org/devguide/>`_.

15110

15111

15112

Are there any published articles about Python that I can reference?

15113

diff -r 8527427914a2 Doc/faq/gui.rst

15114

--- a/Doc/faq/gui.rst

15115

+++ b/Doc/faq/gui.rst

15116

@@ -117,7 +117,7 @@

15117

(http://tix.sourceforge.net/).

15118

15119

Build Tix with SAM enabled, perform the appropriate call to

15120

-:cfunc:`Tclsam_init`, etc. inside Python's

15121

+:c:func:`Tclsam_init`, etc. inside Python's

15122

:file:`Modules/tkappinit.c`, and link with libtclsam and libtksam (you

15123

might include the Tix libraries as well).

15124

15125

@@ -126,7 +126,7 @@

15126

---------------------------------------------------

15127

15128

Yes, and you don't even need threads! But you'll have to restructure your I/O

15129

-code a bit. Tk has the equivalent of Xt's :cfunc:`XtAddInput()` call, which allows you

15130

+code a bit. Tk has the equivalent of Xt's :c:func:`XtAddInput()` call, which allows you

15131

to register a callback function which will be called from the Tk mainloop when

15132

I/O is possible on a file descriptor. Here's what you need::

15133

15134

diff -r 8527427914a2 Doc/faq/library.rst

15135

--- a/Doc/faq/library.rst

15136

+++ b/Doc/faq/library.rst

15137

@@ -410,7 +410,7 @@

15138

15139

Since then, the idea of getting rid of the GIL has occasionally come up but

15140

nobody has found a way to deal with the expected slowdown, and users who don't

15141

-use threads would not be happy if their code ran at half at the speed. Greg's

15142

+use threads would not be happy if their code ran at half the speed. Greg's

15143

free threading patch set has not been kept up-to-date for later Python versions.

15144

15145

This doesn't mean that you can't make good use of Python on multi-CPU machines!

15146

diff -r 8527427914a2 Doc/faq/programming.rst

15147

--- a/Doc/faq/programming.rst

15148

+++ b/Doc/faq/programming.rst

15149

@@ -171,7 +171,7 @@

15150

Thus to get the same effect as::

15151

15152

L2 = []

15153

- for i in range[3]:

15154

+ for i in range(3):

15155

L2.append(L1[i])

15156

15157

it is much shorter and far faster to use ::

15158

@@ -980,7 +980,7 @@

15159

if the line uses something other than whitespace as a separator.

15160

15161

For more complicated input parsing, regular expressions are more powerful

15162

-than C's :cfunc:`sscanf` and better suited for the task.

15163

+than C's :c:func:`sscanf` and better suited for the task.

15164

15165

15166

What does 'UnicodeError: ASCII [decoding,encoding] error: ordinal not in range(128)' mean?

15167

diff -r 8527427914a2 Doc/faq/windows.rst

15168

--- a/Doc/faq/windows.rst

15169

+++ b/Doc/faq/windows.rst

15170

@@ -537,12 +537,12 @@

15171

The Python 1.5.* DLLs (``python15.dll``) are all compiled with MS VC++ 5.0 and

15172

with multithreading-DLL options (``/MD``).

15173

15174

-If you can't change compilers or flags, try using :cfunc:`Py_RunSimpleString`.

15175

+If you can't change compilers or flags, try using :c:func:`Py_RunSimpleString`.

15176

A trick to get it to run an arbitrary file is to construct a call to

15177

:func:`execfile` with the name of your file as argument.

15178

15179

Also note that you can not mix-and-match Debug and Release versions. If you

15180

-wish to use the Debug Multithreaded DLL, then your module *must* have an "_d"

15181

+wish to use the Debug Multithreaded DLL, then your module *must* have ``_d``

15182

appended to the base name.

15183

15184

15185

diff -r 8527427914a2 Doc/glossary.rst

15186

--- a/Doc/glossary.rst

15187

+++ b/Doc/glossary.rst

15188

@@ -27,12 +27,16 @@

15189

:ref:`2to3-reference`.

15190

15191

abstract base class

15192

- :ref:`abstract-base-classes` complement :term:`duck-typing` by

15193

+ Abstract base classes complement :term:`duck-typing` by

15194

providing a way to define interfaces when other techniques like

15195

- :func:`hasattr` would be clumsy. Python comes with many built-in ABCs for

15196

+ :func:`hasattr` would be clumsy or subtly wrong (for example with

15197

+ :ref:`magic methods <new-style-special-lookup>`). ABCs introduce virtual

15198

+ subclasses, which are classes that don't inherit from a class but are

15199

+ still recognized by :func:`isinstance` and :func:`issubclass`; see the

15200

+ :mod:`abc` module documentation. Python comes with many built-in ABCs for

15201

data structures (in the :mod:`collections` module), numbers (in the

15202

:mod:`numbers` module), and streams (in the :mod:`io` module). You can

15203

- create your own ABC with the :mod:`abc` module.

15204

+ create your own ABCs with the :mod:`abc` module.

15205

15206

argument

15207

A value passed to a function or method, assigned to a named local

15208

@@ -57,11 +61,14 @@

15209

15210

bytecode

15211

Python source code is compiled into bytecode, the internal representation

15212

- of a Python program in the interpreter. The bytecode is also cached in

15213

- ``.pyc`` and ``.pyo`` files so that executing the same file is faster the

15214

- second time (recompilation from source to bytecode can be avoided). This

15215

- "intermediate language" is said to run on a :term:`virtual machine`

15216

- that executes the machine code corresponding to each bytecode.

15217

+ of a Python program in the CPython interpreter. The bytecode is also

15218

+ cached in ``.pyc`` and ``.pyo`` files so that executing the same file is

15219

+ faster the second time (recompilation from source to bytecode can be

15220

+ avoided). This "intermediate language" is said to run on a

15221

+ :term:`virtual machine` that executes the machine code corresponding to

15222

+ each bytecode. Do note that bytecodes are not expected to work between

15223

+ different Python virtual machines, nor to be stable between Python

15224

+ releases.

15225

15226

A list of bytecode instructions can be found in the documentation for

15227

:ref:`the dis module <bytecodes>`.

15228

@@ -127,8 +134,9 @@

15229

def f(...):

15230

...

15231

15232

- See :ref:`the documentation for function definition <function>` for more

15233

- about decorators.

15234

+ The same concept exists for classes, but is less commonly used there. See

15235

+ the documentation for :ref:`function definitions <function>` and

15236

+ :ref:`class definitions <class>` for more about decorators.

15237

15238

descriptor

15239

Any *new-style* object which defines the methods :meth:`__get__`,

15240

@@ -164,8 +172,8 @@

15241

well-designed code improves its flexibility by allowing polymorphic

15242

substitution. Duck-typing avoids tests using :func:`type` or

15243

:func:`isinstance`. (Note, however, that duck-typing can be complemented

15244

- with :term:`abstract base class`\ es.) Instead, it typically employs

15245

- :func:`hasattr` tests or :term:`EAFP` programming.

15246

+ with :term:`abstract base classes <abstract base class>`.) Instead, it

15247

+ typically employs :func:`hasattr` tests or :term:`EAFP` programming.

15248

15249

EAFP

15250

Easier to ask for forgiveness than permission. This common Python coding

15251

@@ -177,17 +185,34 @@

15252

15253

expression

15254

A piece of syntax which can be evaluated to some value. In other words,

15255

- an expression is an accumulation of expression elements like literals, names,

15256

- attribute access, operators or function calls which all return a value.

15257

- In contrast to many other languages, not all language constructs are expressions.

15258

- There are also :term:`statement`\s which cannot be used as expressions,

15259

- such as :keyword:`print` or :keyword:`if`. Assignments are also statements,

15260

- not expressions.

15261

+ an expression is an accumulation of expression elements like literals,

15262

+ names, attribute access, operators or function calls which all return a

15263

+ value. In contrast to many other languages, not all language constructs

15264

+ are expressions. There are also :term:`statement`\s which cannot be used

15265

+ as expressions, such as :keyword:`print` or :keyword:`if`. Assignments

15266

+ are also statements, not expressions.

15267

15268

extension module

15269

A module written in C or C++, using Python's C API to interact with the

15270

core and with user code.

15271

15272

+ file object

15273

+ An object exposing a file-oriented API (with methods such as

15274

+ :meth:`read()` or :meth:`write()`) to an underlying resource. Depending

15275

+ on the way it was created, a file object can mediate access to a real

15276

+ on-disk file or to another other type of storage or communication device

15277

+ (for example standard input/output, in-memory buffers, sockets, pipes,

15278

+ etc.). File objects are also called :dfn:`file-like objects` or

15279

+ :dfn:`streams`.

15280

+

15281

+ There are actually three categories of file objects: raw binary files,

15282

+ buffered binary files and text files. Their interfaces are defined in the

15283

+ :mod:`io` module. The canonical way to create a file object is by using

15284

+ the :func:`open` function.

15285

+

15286

+ file-like object

15287

+ A synonym for :term:`file object`.

15288

+

15289

finder

15290

An object that tries to find the :term:`loader` for a module. It must

15291

implement a method named :meth:`find_module`. See :pep:`302` for

15292

@@ -334,7 +359,7 @@

15293

slowly. See also :term:`interactive`.

15294

15295

iterable

15296

- A container object capable of returning its members one at a

15297

+ An object capable of returning its members one at a

15298

time. Examples of iterables include all sequence types (such as

15299

:class:`list`, :class:`str`, and :class:`tuple`) and some non-sequence

15300

types like :class:`dict` and :class:`file` and objects of any classes you

15301

@@ -403,6 +428,12 @@

15302

the :term:`EAFP` approach and is characterized by the presence of many

15303

:keyword:`if` statements.

15304

15305

+ In a multi-threaded environment, the LBYL approach can risk introducing a

15306

+ race condition between "the looking" and "the leaping". For example, the

15307

+ code, ``if key in mapping: return mapping[key]`` can fail if another

15308

+ thread removes *key* from *mapping* after the test, but before the lookup.

15309

+ This issue can be solved with locks or by using the EAFP approach.

15310

+

15311

list

15312

A built-in Python :term:`sequence`. Despite its name it is more akin

15313

to an array in other languages than to a linked list since access to

15314

@@ -423,9 +454,10 @@

15315

15316

mapping

15317

A container object that supports arbitrary key lookups and implements the

15318

- methods specified in the :class:`Mapping` or :class:`MutableMapping`

15319

- :ref:`abstract base classes <abstract-base-classes>`. Examples include

15320

- :class:`dict`, :class:`collections.defaultdict`,

15321

+ methods specified in the :class:`~collections.Mapping` or

15322

+ :class:`~collections.MutableMapping`

15323

+ :ref:`abstract base classes <collections-abstract-base-classes>`. Examples

15324

+ include :class:`dict`, :class:`collections.defaultdict`,

15325

:class:`collections.OrderedDict` and :class:`collections.Counter`.

15326

15327

metaclass

15328

@@ -447,6 +479,14 @@

15329

its first :term:`argument` (which is usually called ``self``).

15330

See :term:`function` and :term:`nested scope`.

15331

15332

+ method resolution order

15333

+ Method Resolution Order is the order in which base classes are searched

15334

+ for a member during lookup. See `The Python 2.3 Method Resolution Order

15335

+ <http://www.python.org/download/releases/2.3/mro/>`_.

15336

+

15337

+ MRO

15338

+ See :term:`method resolution order`.

15339

+

15340

mutable

15341

Mutable objects can change their value but keep their :func:`id`. See

15342

also :term:`immutable`.

15343

@@ -505,9 +545,9 @@

15344

:term:`argument`.

15345

15346

Python 3000

15347

- Nickname for the next major Python version, 3.0 (coined long ago

15348

- when the release of version 3 was something in the distant future.) This

15349

- is also abbreviated "Py3k".

15350

+ Nickname for the Python 3.x release line (coined long ago when the release

15351

+ of version 3 was something in the distant future.) This is also

15352

+ abbreviated "Py3k".

15353

15354

Pythonic

15355

An idea or piece of code which closely follows the most common idioms

15356

@@ -530,7 +570,7 @@

15357

object drops to zero, it is deallocated. Reference counting is

15358

generally not visible to Python code, but it is a key element of the

15359

:term:`CPython` implementation. The :mod:`sys` module defines a

15360

- :func:`getrefcount` function that programmers can call to return the

15361

+ :func:`~sys.getrefcount` function that programmers can call to return the

15362

reference count for a particular object.

15363

15364

__slots__

15365

@@ -566,7 +606,15 @@

15366

statement

15367

A statement is part of a suite (a "block" of code). A statement is either

15368

an :term:`expression` or a one of several constructs with a keyword, such

15369

- as :keyword:`if`, :keyword:`while` or :keyword:`print`.

15370

+ as :keyword:`if`, :keyword:`while` or :keyword:`for`.

15371

+

15372

+ struct sequence

15373

+ A tuple with named elements. Struct sequences expose an interface similiar

15374

+ to :term:`named tuple` in that elements can either be accessed either by

15375

+ index or as an attribute. However, they do not have any of the named tuple

15376

+ methods like :meth:`~collections.somenamedtuple._make` or

15377

+ :meth:`~collections.somenamedtuple._asdict`. Examples of struct sequences

15378

+ include :data:`sys.float_info` and the return value of :func:`os.stat`.

15379

15380

triple-quoted string

15381

A string which is bound by three instances of either a quotation mark

15382

diff -r 8527427914a2 Doc/howto/cporting.rst

15383

--- a/Doc/howto/cporting.rst

15384

+++ b/Doc/howto/cporting.rst

15385

@@ -1,5 +1,7 @@

15386

.. highlightlang:: c

15387

15388

+.. _cporting-howto:

15389

+

15390

********************************

15391

Porting Extension Modules to 3.0

15392

********************************

15393

@@ -20,7 +22,7 @@

15394

=======================

15395

15396

The easiest way to compile only some code for 3.0 is to check if

15397

-:cmacro:`PY_MAJOR_VERSION` is greater than or equal to 3. ::

15398

+:c:macro:`PY_MAJOR_VERSION` is greater than or equal to 3. ::

15399

15400

#if PY_MAJOR_VERSION >= 3

15401

#define IS_PY3K

15402

@@ -45,12 +47,12 @@

15403

2.x's :func:`unicode` (``PyUnicode_*``). The old 8-bit string type has become

15404

:func:`bytes`. Python 2.6 and later provide a compatibility header,

15405

:file:`bytesobject.h`, mapping ``PyBytes`` names to ``PyString`` ones. For best

15406

-compatibility with 3.0, :ctype:`PyUnicode` should be used for textual data and

15407

-:ctype:`PyBytes` for binary data. It's also important to remember that

15408

-:ctype:`PyBytes` and :ctype:`PyUnicode` in 3.0 are not interchangeable like

15409

-:ctype:`PyString` and :ctype:`PyUnicode` are in 2.x. The following example

15410

-shows best practices with regards to :ctype:`PyUnicode`, :ctype:`PyString`,

15411

-and :ctype:`PyBytes`. ::

15412

+compatibility with 3.0, :c:type:`PyUnicode` should be used for textual data and

15413

+:c:type:`PyBytes` for binary data. It's also important to remember that

15414

+:c:type:`PyBytes` and :c:type:`PyUnicode` in 3.0 are not interchangeable like

15415

+:c:type:`PyString` and :c:type:`PyUnicode` are in 2.x. The following example

15416

+shows best practices with regards to :c:type:`PyUnicode`, :c:type:`PyString`,

15417

+and :c:type:`PyBytes`. ::

15418

15419

#include "stdlib.h"

15420

#include "Python.h"

15421

@@ -207,6 +209,58 @@

15422

}

15423

15424

15425

+CObject replaced with Capsule

15426

+=============================

15427

+

15428

+The :c:type:`Capsule` object was introduced in Python 3.1 and 2.7 to replace

15429

+:c:type:`CObject`. CObjects were useful,

15430

+but the :c:type:`CObject` API was problematic: it didn't permit distinguishing

15431

+between valid CObjects, which allowed mismatched CObjects to crash the

15432

+interpreter, and some of its APIs relied on undefined behavior in C.

15433

+(For further reading on the rationale behind Capsules, please see :issue:`5630`.)

15434

+

15435

+If you're currently using CObjects, and you want to migrate to 3.1 or newer,

15436

+you'll need to switch to Capsules.

15437

+:c:type:`CObject` was deprecated in 3.1 and 2.7 and completely removed in

15438

+Python 3.2. If you only support 2.7, or 3.1 and above, you

15439

+can simply switch to :c:type:`Capsule`. If you need to support 3.0 or

15440

+versions of Python earlier than 2.7 you'll have to support both CObjects

15441

+and Capsules.

15442

+

15443

+The following example header file :file:`capsulethunk.h` may

15444

+solve the problem for you;

15445

+simply write your code against the :c:type:`Capsule` API, include

15446

+this header file after ``"Python.h"``, and you'll automatically use CObjects

15447

+in Python 3.0 or versions earlier than 2.7.

15448

+

15449

+:file:`capsulethunk.h` simulates Capsules using CObjects. However,

15450

+:c:type:`CObject` provides no place to store the capsule's "name". As a

15451

+result the simulated :c:type:`Capsule` objects created by :file:`capsulethunk.h`

15452

+behave slightly differently from real Capsules. Specifically:

15453

+

15454

+ * The name parameter passed in to :c:func:`PyCapsule_New` is ignored.

15455

+

15456

+ * The name parameter passed in to :c:func:`PyCapsule_IsValid` and

15457

+ :c:func:`PyCapsule_GetPointer` is ignored, and no error checking

15458

+ of the name is performed.

15459

+

15460

+ * :c:func:`PyCapsule_GetName` always returns NULL.

15461

+

15462

+ * :c:func:`PyCapsule_SetName` always throws an exception and

15463

+ returns failure. (Since there's no way to store a name

15464

+ in a CObject, noisy failure of :c:func:`PyCapsule_SetName`

15465

+ was deemed preferable to silent failure here. If this is

15466

+ inconveient, feel free to modify your local

15467

+ copy as you see fit.)

15468

+

15469

+You can find :file:`capsulethunk.h` in the Python source distribution

15470

+in the :file:`Doc/includes` directory. We also include it here for

15471

+your reference; here is :file:`capsulethunk.h`:

15472

+

15473

+.. literalinclude:: ../includes/capsulethunk.h

15474

+

15475

+

15476

+

15477

Other options

15478

=============

15479

15480

diff -r 8527427914a2 Doc/howto/descriptor.rst

15481

--- a/Doc/howto/descriptor.rst

15482

+++ b/Doc/howto/descriptor.rst

15483

@@ -42,7 +42,7 @@

15484

15485

Descriptors are a powerful, general purpose protocol. They are the mechanism

15486

behind properties, methods, static methods, class methods, and :func:`super()`.

15487

-They are used used throughout Python itself to implement the new style classes

15488

+They are used throughout Python itself to implement the new style classes

15489

introduced in version 2.2. Descriptors simplify the underlying C-code and offer

15490

a flexible set of new tools for everyday Python programs.

15491

15492

@@ -97,7 +97,7 @@

15493

implementation works through a precedence chain that gives data descriptors

15494

priority over instance variables, instance variables priority over non-data

15495

descriptors, and assigns lowest priority to :meth:`__getattr__` if provided. The

15496

-full C implementation can be found in :cfunc:`PyObject_GenericGetAttr()` in

15497

+full C implementation can be found in :c:func:`PyObject_GenericGetAttr()` in

15498

`Objects/object.c <http://svn.python.org/view/python/trunk/Objects/object.c?view=markup>`_\.

15499

15500

For classes, the machinery is in :meth:`type.__getattribute__` which transforms

15501

@@ -131,7 +131,7 @@

15502

Note, in Python 2.2, ``super(B, obj).m()`` would only invoke :meth:`__get__` if

15503

``m`` was a data descriptor. In Python 2.3, non-data descriptors also get

15504

invoked unless an old-style class is involved. The implementation details are

15505

-in :cfunc:`super_getattro()` in

15506

+in :c:func:`super_getattro()` in

15507

`Objects/typeobject.c <http://svn.python.org/view/python/trunk/Objects/typeobject.c?view=markup>`_

15508

and a pure Python equivalent can be found in `Guido's Tutorial`_.

15509

15510

@@ -297,7 +297,7 @@

15511

15512

The output suggests that bound and unbound methods are two different types.

15513

While they could have been implemented that way, the actual C implementation of

15514

-:ctype:`PyMethod_Type` in

15515

+:c:type:`PyMethod_Type` in

15516

`Objects/classobject.c <http://svn.python.org/view/python/trunk/Objects/classobject.c?view=markup>`_

15517

is a single object with two different representations depending on whether the

15518

:attr:`im_self` field is set or is *NULL* (the C equivalent of *None*).

15519

diff -r 8527427914a2 Doc/howto/doanddont.rst

15520

--- a/Doc/howto/doanddont.rst

15521

+++ b/Doc/howto/doanddont.rst

15522

@@ -32,8 +32,8 @@

15523

versions of Python do not check for the invalidity, it does not make it more

15524

valid, no more than having a smart lawyer makes a man innocent. Do not use it

15525

like that ever. Even in versions where it was accepted, it made the function

15526

-execution slower, because the compiler could not be certain which names are

15527

-local and which are global. In Python 2.1 this construct causes warnings, and

15528

+execution slower, because the compiler could not be certain which names were

15529

+local and which were global. In Python 2.1 this construct causes warnings, and

15530

sometimes even errors.

15531

15532

15533

@@ -46,7 +46,7 @@

15534

in your favourite editor. You also open yourself to trouble in the future, if

15535

some module grows additional functions or classes.

15536

15537

-One of the most awful question asked on the newsgroup is why this code::

15538

+One of the most awful questions asked on the newsgroup is why this code::

15539

15540

f = open("www")

15541

f.read()

15542

@@ -113,7 +113,7 @@

15543

15544

This is a "don't" which is much weaker than the previous "don't"s but is still

15545

something you should not do if you don't have good reasons to do that. The

15546

-reason it is usually bad idea is because you suddenly have an object which lives

15547

+reason it is usually a bad idea is because you suddenly have an object which lives

15548

in two separate namespaces. When the binding in one namespace changes, the

15549

binding in the other will not, so there will be a discrepancy between them. This

15550

happens when, for example, one module is reloaded, or changes the definition of

15551

diff -r 8527427914a2 Doc/howto/functional.rst

15552

--- a/Doc/howto/functional.rst

15553

+++ b/Doc/howto/functional.rst

15554

@@ -44,15 +44,14 @@

15555

functional languages include the ML family (Standard ML, OCaml, and other

15556

variants) and Haskell.

15557

15558

-The designers of some computer languages choose to emphasize one

15559

-particular approach to programming. This often makes it difficult to

15560

-write programs that use a different approach. Other languages are

15561

-multi-paradigm languages that support several different approaches.

15562

-Lisp, C++, and Python are multi-paradigm; you can write programs or

15563

-libraries that are largely procedural, object-oriented, or functional

15564

-in all of these languages. In a large program, different sections

15565

-might be written using different approaches; the GUI might be

15566

-object-oriented while the processing logic is procedural or

15567

+The designers of some computer languages choose to emphasize one particular

15568

+approach to programming. This often makes it difficult to write programs that

15569

+use a different approach. Other languages are multi-paradigm languages that

15570

+support several different approaches. Lisp, C++, and Python are

15571

+multi-paradigm; you can write programs or libraries that are largely

15572

+procedural, object-oriented, or functional in all of these languages. In a

15573

+large program, different sections might be written using different approaches;

15574

+the GUI might be object-oriented while the processing logic is procedural or

15575

functional, for example.

15576

15577

In a functional program, input flows through a set of functions. Each function

15578

@@ -1115,132 +1114,6 @@

15579

Consult the operator module's documentation for a complete list.

15580

15581

15582

-

15583

-The functional module

15584

----------------------

15585

-

15586

-Collin Winter's `functional module <http://oakwinter.com/code/functional/>`__

15587

-provides a number of more advanced tools for functional programming. It also

15588

-reimplements several Python built-ins, trying to make them more intuitive to

15589

-those used to functional programming in other languages.

15590

-

15591

-This section contains an introduction to some of the most important functions in

15592

-``functional``; full documentation can be found at `the project's website

15593

-<http://oakwinter.com/code/functional/documentation/>`__.

15594

-

15595

-``compose(outer, inner, unpack=False)``

15596

-

15597

-The ``compose()`` function implements function composition. In other words, it

15598

-returns a wrapper around the ``outer`` and ``inner`` callables, such that the

15599

-return value from ``inner`` is fed directly to ``outer``. That is, ::

15600

-

15601

- >>> def add(a, b):

15602

- ... return a + b

15603

- ...

15604

- >>> def double(a):

15605

- ... return 2 * a

15606

- ...

15607

- >>> compose(double, add)(5, 6)

15608

- 22

15609

-

15610

-is equivalent to ::

15611

-

15612

- >>> double(add(5, 6))

15613

- 22

15614

-

15615

-The ``unpack`` keyword is provided to work around the fact that Python functions

15616

-are not always `fully curried <http://en.wikipedia.org/wiki/Currying>`__. By

15617

-default, it is expected that the ``inner`` function will return a single object

15618

-and that the ``outer`` function will take a single argument. Setting the

15619

-``unpack`` argument causes ``compose`` to expect a tuple from ``inner`` which

15620

-will be expanded before being passed to ``outer``. Put simply, ::

15621

-

15622

- compose(f, g)(5, 6)

15623

-

15624

-is equivalent to::

15625

-

15626

- f(g(5, 6))

15627

-

15628

-while ::

15629

-

15630

- compose(f, g, unpack=True)(5, 6)

15631

-

15632

-is equivalent to::

15633

-

15634

- f(*g(5, 6))

15635

-

15636

-Even though ``compose()`` only accepts two functions, it's trivial to build up a

15637

-version that will compose any number of functions. We'll use ``reduce()``,

15638

-``compose()`` and ``partial()`` (the last of which is provided by both

15639

-``functional`` and ``functools``). ::

15640

-

15641

- from functional import compose, partial

15642

-

15643

- multi_compose = partial(reduce, compose)

15644

-

15645

-

15646

-We can also use ``map()``, ``compose()`` and ``partial()`` to craft a version of

15647

-``"".join(...)`` that converts its arguments to string::

15648

-

15649

- from functional import compose, partial

15650

-

15651

- join = compose("".join, partial(map, str))

15652

-

15653

-

15654

-``flip(func)``

15655

-

15656

-``flip()`` wraps the callable in ``func`` and causes it to receive its

15657

-non-keyword arguments in reverse order. ::

15658

-

15659

- >>> def triple(a, b, c):

15660

- ... return (a, b, c)

15661

- ...

15662

- >>> triple(5, 6, 7)

15663

- (5, 6, 7)

15664

- >>>

15665

- >>> flipped_triple = flip(triple)

15666

- >>> flipped_triple(5, 6, 7)

15667

- (7, 6, 5)

15668

-

15669

-``foldl(func, start, iterable)``

15670

-

15671

-``foldl()`` takes a binary function, a starting value (usually some kind of

15672

-'zero'), and an iterable. The function is applied to the starting value and the

15673

-first element of the list, then the result of that and the second element of the

15674

-list, then the result of that and the third element of the list, and so on.

15675

-

15676

-This means that a call such as::

15677

-

15678

- foldl(f, 0, [1, 2, 3])

15679

-

15680

-is equivalent to::

15681

-

15682

- f(f(f(0, 1), 2), 3)

15683

-

15684

-

15685

-``foldl()`` is roughly equivalent to the following recursive function::

15686

-

15687

- def foldl(func, start, seq):

15688

- if len(seq) == 0:

15689

- return start

15690

-

15691

- return foldl(func, func(start, seq[0]), seq[1:])

15692

-

15693

-Speaking of equivalence, the above ``foldl`` call can be expressed in terms of

15694

-the built-in ``reduce`` like so::

15695

-

15696

- reduce(f, [1, 2, 3], 0)

15697

-

15698

-

15699

-We can use ``foldl()``, ``operator.concat()`` and ``partial()`` to write a

15700

-cleaner, more aesthetically-pleasing version of Python's ``"".join(...)``

15701

-idiom::

15702

-

15703

- from functional import foldl, partial from operator import concat

15704

-

15705

- join = partial(foldl, concat, "")

15706

-

15707

-

15708

Revision History and Acknowledgements

15709

=====================================

15710

15711

@@ -1296,9 +1169,10 @@

15712

15713

Mertz also wrote a 3-part series of articles on functional programming

15714

for IBM's DeveloperWorks site; see

15715

-`part 1 <http://www-128.ibm.com/developerworks/library/l-prog.html>`__,

15716

-`part 2 <http://www-128.ibm.com/developerworks/library/l-prog2.html>`__, and

15717

-`part 3 <http://www-128.ibm.com/developerworks/linux/library/l-prog3.html>`__,

15718

+

15719

+`part 1 <http://www.ibm.com/developerworks/linux/library/l-prog/index.html>`__,

15720

+`part 2 <http://www.ibm.com/developerworks/linux/library/l-prog2/index.html>`__, and

15721

+`part 3 <http://www.ibm.com/developerworks/linux/library/l-prog3/index.html>`__,

15722

15723

15724

Python documentation

15725

diff -r 8527427914a2 Doc/howto/index.rst

15726

--- a/Doc/howto/index.rst

15727

+++ b/Doc/howto/index.rst

15728

@@ -14,6 +14,7 @@

15729

:maxdepth: 1

15730

15731

advocacy.rst

15732

+ pyporting.rst

15733

cporting.rst

15734

curses.rst

15735

descriptor.rst

15736

diff -r 8527427914a2 Doc/howto/logging-cookbook.rst

15737

--- a/Doc/howto/logging-cookbook.rst

15738

+++ b/Doc/howto/logging-cookbook.rst

15739

@@ -610,9 +610,10 @@

15740

to have all the processes log to a :class:`SocketHandler`, and have a separate

15741

process which implements a socket server which reads from the socket and logs

15742

to file. (If you prefer, you can dedicate one thread in one of the existing

15743

-processes to perform this function.) The following section documents this

15744

-approach in more detail and includes a working socket receiver which can be

15745

-used as a starting point for you to adapt in your own applications.

15746

+processes to perform this function.) :ref:`This section <network-logging>`

15747

+documents this approach in more detail and includes a working socket receiver

15748

+which can be used as a starting point for you to adapt in your own

15749

+applications.

15750

15751

If you are using a recent version of Python which includes the

15752

:mod:`multiprocessing` module, you could write your own handler which uses the

15753

@@ -679,6 +680,68 @@

15754

``.1``. Each of the existing backup files is renamed to increment the suffix

15755

(``.1`` becomes ``.2``, etc.) and the ``.6`` file is erased.

15756

15757

-Obviously this example sets the log length much much too small as an extreme

15758

+Obviously this example sets the log length much too small as an extreme

15759

example. You would want to set *maxBytes* to an appropriate value.

15760

15761

+An example dictionary-based configuration

15762

+-----------------------------------------

15763

+

15764

+Below is an example of a logging configuration dictionary - it's taken from

15765

+the `documentation on the Django project <https://docs.djangoproject.com/en/1.3/topics/logging/#configuring-logging>`_.

15766

+This dictionary is passed to :func:`~logging.config.dictConfig` to put the configuration into effect::

15767

+

15768

+ LOGGING = {

15769

+ 'version': 1,

15770

+ 'disable_existing_loggers': True,

15771

+ 'formatters': {

15772

+ 'verbose': {

15773

+ 'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'

15774

+ },

15775

+ 'simple': {

15776

+ 'format': '%(levelname)s %(message)s'

15777

+ },

15778

+ },

15779

+ 'filters': {

15780

+ 'special': {

15781

+ '()': 'project.logging.SpecialFilter',

15782

+ 'foo': 'bar',

15783

+ }

15784

+ },

15785

+ 'handlers': {

15786

+ 'null': {

15787

+ 'level':'DEBUG',

15788

+ 'class':'django.utils.log.NullHandler',

15789

+ },

15790

+ 'console':{

15791

+ 'level':'DEBUG',

15792

+ 'class':'logging.StreamHandler',

15793

+ 'formatter': 'simple'

15794

+ },

15795

+ 'mail_admins': {

15796

+ 'level': 'ERROR',

15797

+ 'class': 'django.utils.log.AdminEmailHandler',

15798

+ 'filters': ['special']

15799

+ }

15800

+ },

15801

+ 'loggers': {

15802

+ 'django': {

15803

+ 'handlers':['null'],

15804

+ 'propagate': True,

15805

+ 'level':'INFO',

15806

+ },

15807

+ 'django.request': {

15808

+ 'handlers': ['mail_admins'],

15809

+ 'level': 'ERROR',

15810

+ 'propagate': False,

15811

+ },

15812

+ 'myproject.custom': {

15813

+ 'handlers': ['console', 'mail_admins'],

15814

+ 'level': 'INFO',

15815

+ 'filters': ['special']

15816

+ }

15817

+ }

15818

+ }

15819

+

15820

+For more information about this configuration, you can see the `relevant

15821

+section <https://docs.djangoproject.com/en/1.3/topics/logging/#configuring-logging>`_

15822

+of the Django documentation.

15823

diff -r 8527427914a2 Doc/howto/logging.rst

15824

--- a/Doc/howto/logging.rst

15825

+++ b/Doc/howto/logging.rst

15826

@@ -670,7 +670,7 @@

15827

version: 1

15828

formatters:

15829

simple:

15830

- format: format=%(asctime)s - %(name)s - %(levelname)s - %(message)s

15831

+ format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'

15832

handlers:

15833

console:

15834

class: logging.StreamHandler

15835

diff -r 8527427914a2 Doc/howto/pyporting.rst

15836

--- /dev/null

15837

+++ b/Doc/howto/pyporting.rst

15838

@@ -0,0 +1,703 @@

15839

+.. _pyporting-howto:

15840

+

15841

+*********************************

15842

+Porting Python 2 Code to Python 3

15843

+*********************************

15844

+

15845

+:author: Brett Cannon

15846

+

15847

+.. topic:: Abstract

15848

+

15849

+ With Python 3 being the future of Python while Python 2 is still in active

15850

+ use, it is good to have your project available for both major releases of

15851

+ Python. This guide is meant to help you choose which strategy works best

15852

+ for your project to support both Python 2 & 3 along with how to execute

15853

+ that strategy.

15854

+

15855

+ If you are looking to port an extension module instead of pure Python code,

15856

+ please see :ref:`cporting-howto`.

15857

+

15858

+

15859

+Choosing a Strategy

15860

+===================

15861

+

15862

+When a project makes the decision that it's time to support both Python 2 & 3,

15863

+a decision needs to be made as to how to go about accomplishing that goal.

15864

+The chosen strategy will depend on how large the project's existing

15865

+codebase is and how much divergence you want from your Python 2 codebase from

15866

+your Python 3 one (e.g., starting a new version with Python 3).

15867

+

15868

+If your project is brand-new or does not have a large codebase, then you may

15869

+want to consider writing/porting :ref:`all of your code for Python 3

15870

+and use 3to2 <use_3to2>` to port your code for Python 2.

15871

+

15872

+If you would prefer to maintain a codebase which is semantically **and**

15873

+syntactically compatible with Python 2 & 3 simultaneously, you can write

15874

+:ref:`use_same_source`. While this tends to lead to somewhat non-idiomatic

15875

+code, it does mean you keep a rapid development process for you, the developer.

15876

+

15877

+Finally, you do have the option of :ref:`using 2to3 <use_2to3>` to translate

15878

+Python 2 code into Python 3 code (with some manual help). This can take the

15879

+form of branching your code and using 2to3 to start a Python 3 branch. You can

15880

+also have users perform the translation as installation time automatically so

15881

+that you only have to maintain a Python 2 codebase.

15882

+

15883

+Regardless of which approach you choose, porting is not as hard or

15884

+time-consuming as you might initially think. You can also tackle the problem

15885

+piece-meal as a good portion of porting is simply updating your code to follow

15886

+current best practices in a Python 2/3 compatible way.

15887

+

15888

+

15889

+Universal Bits of Advice

15890

+------------------------

15891

+

15892

+Regardless of what strategy you pick, there are a few things you should

15893

+consider.

15894

+

15895

+One is make sure you have a robust test suite. You need to make sure everything

15896

+continues to work, just like when you support a new minor version of Python.

15897

+This means making sure your test suite is thorough and is ported properly

15898

+between Python 2 & 3. You will also most likely want to use something like tox_

15899

+to automate testing between both a Python 2 and Python 3 VM.

15900

+

15901

+Two, once your project has Python 3 support, make sure to add the proper

15902

+classifier on the Cheeseshop_ (PyPI_). To have your project listed as Python 3

15903

+compatible it must have the

15904

+`Python 3 classifier <http://pypi.python.org/pypi?:action=browse&c=533>`_

15905

+(from

15906

+http://techspot.zzzeek.org/2011/01/24/zzzeek-s-guide-to-python-3-porting/)::

15907

+

15908

+ setup(

15909

+ name='Your Library',

15910

+ version='1.0',

15911

+ classifiers=[

15912

+ # make sure to use :: Python *and* :: Python :: 3 so

15913

+ # that pypi can list the package on the python 3 page

15914

+ 'Programming Language :: Python',

15915

+ 'Programming Language :: Python :: 3'

15916

+ ],

15917

+ packages=['yourlibrary'],

15918

+ # make sure to add custom_fixers to the MANIFEST.in

15919

+ include_package_data=True,

15920

+ # ...

15921

+ )

15922

+

15923

+

15924

+Doing so will cause your project to show up in the

15925

+`Python 3 packages list

15926

+<http://pypi.python.org/pypi?:action=browse&c=533&show=all>`_. You will know

15927

+you set the classifier properly as visiting your project page on the Cheeseshop

15928

+will show a Python 3 logo in the upper-left corner of the page.

15929

+

15930

+Three, the six_ project provides a library which helps iron out differences

15931

+between Python 2 & 3. If you find there is a sticky point that is a continual

15932

+point of contention in your translation or maintenance of code, consider using

15933

+a source-compatible solution relying on six. If you have to create your own

15934

+Python 2/3 compatible solution, you can use ``sys.version_info[0] >= 3`` as a

15935

+guard.

15936

+

15937

+Four, read all the approaches. Just because some bit of advice applies to one

15938

+approach more than another doesn't mean that some advice doesn't apply to other

15939

+strategies.

15940

+

15941

+Five, drop support for older Python versions if possible. `Python 2.5`_

15942

+introduced a lot of useful syntax and libraries which have become idiomatic

15943

+in Python 3. `Python 2.6`_ introduced future statements which makes

15944

+compatibility much easier if you are going from Python 2 to 3.

15945

+`Python 2.7`_ continues the trend in the stdlib. So choose the newest version

15946

+of Python which you believe can be your minimum support version

15947

+and work from there.

15948

+

15949

+

15950

+.. _tox: http://codespeak.net/tox/

15951

+.. _Cheeseshop:

15952

+.. _PyPI: http://pypi.python.org/

15953

+.. _six: http://packages.python.org/six

15954

+.. _Python 2.7: http://www.python.org/2.7.x

15955

+.. _Python 2.6: http://www.python.org/2.6.x

15956

+.. _Python 2.5: http://www.python.org/2.5.x

15957

+.. _Python 2.4: http://www.python.org/2.4.x

15958

+.. _Python 2.3: http://www.python.org/2.3.x

15959

+.. _Python 2.2: http://www.python.org/2.2.x

15960

+

15961

+

15962

+.. _use_3to2:

15963

+

15964

+Python 3 and 3to2

15965

+=================

15966

+

15967

+If you are starting a new project or your codebase is small enough, you may

15968

+want to consider writing your code for Python 3 and backporting to Python 2

15969

+using 3to2_. Thanks to Python 3 being more strict about things than Python 2

15970

+(e.g., bytes vs. strings), the source translation can be easier and more

15971

+straightforward than from Python 2 to 3. Plus it gives you more direct

15972

+experience developing in Python 3 which, since it is the future of Python, is a

15973

+good thing long-term.

15974

+

15975

+A drawback of this approach is that 3to2 is a third-party project. This means

15976

+that the Python core developers (and thus this guide) can make no promises

15977

+about how well 3to2 works at any time. There is nothing to suggest, though,

15978

+that 3to2 is not a high-quality project.

15979

+

15980

+

15981

+.. _3to2: https://bitbucket.org/amentajo/lib3to2/overview

15982

+

15983

+

15984

+.. _use_2to3:

15985

+

15986

+Python 2 and 2to3

15987

+=================

15988

+

15989

+Included with Python since 2.6, the 2to3_ tool (and :mod:`lib2to3` module)

15990

+helps with porting Python 2 to Python 3 by performing various source

15991

+translations. This is a perfect solution for projects which wish to branch

15992

+their Python 3 code from their Python 2 codebase and maintain them as

15993

+independent codebases. You can even begin preparing to use this approach

15994

+today by writing future-compatible Python code which works cleanly in

15995

+Python 2 in conjunction with 2to3; all steps outlined below will work

15996

+with Python 2 code up to the point when the actual use of 2to3 occurs.

15997

+

15998

+Use of 2to3 as an on-demand translation step at install time is also possible,

15999

+preventing the need to maintain a separate Python 3 codebase, but this approach

16000

+does come with some drawbacks. While users will only have to pay the

16001

+translation cost once at installation, you as a developer will need to pay the

16002

+cost regularly during development. If your codebase is sufficiently large

16003

+enough then the translation step ends up acting like a compilation step,

16004

+robbing you of the rapid development process you are used to with Python.

16005

+Obviously the time required to translate a project will vary, so do an

16006

+experimental translation just to see how long it takes to evaluate whether you

16007

+prefer this approach compared to using :ref:`use_same_source` or simply keeping

16008

+a separate Python 3 codebase.

16009

+

16010

+Below are the typical steps taken by a project which uses a 2to3-based approach

16011

+to supporting Python 2 & 3.

16012

+

16013

+

16014

+Support Python 2.7

16015

+------------------

16016

+

16017

+As a first step, make sure that your project is compatible with `Python 2.7`_.

16018

+This is just good to do as Python 2.7 is the last release of Python 2 and thus

16019

+will be used for a rather long time. It also allows for use of the ``-3`` flag

16020

+to Python to help discover places in your code which 2to3 cannot handle but are

16021

+known to cause issues.

16022

+

16023

+Try to Support `Python 2.6`_ and Newer Only

16024

+-------------------------------------------

16025

+

16026

+While not possible for all projects, if you can support `Python 2.6`_ and newer

16027

+**only**, your life will be much easier. Various future statements, stdlib

16028

+additions, etc. exist only in Python 2.6 and later which greatly assist in

16029

+porting to Python 3. But if you project must keep support for `Python 2.5`_ (or

16030

+even `Python 2.4`_) then it is still possible to port to Python 3.

16031

+

16032

+Below are the benefits you gain if you only have to support Python 2.6 and

16033

+newer. Some of these options are personal choice while others are

16034

+**strongly** recommended (the ones that are more for personal choice are

16035

+labeled as such). If you continue to support older versions of Python then you

16036

+at least need to watch out for situations that these solutions fix.

16037

+

16038

+

16039

+``from __future__ import print_function``

16040

+'''''''''''''''''''''''''''''''''''''''''

16041

+

16042

+This is a personal choice. 2to3 handles the translation from the print

16043

+statement to the print function rather well so this is an optional step. This

16044

+future statement does help, though, with getting used to typing

16045

+``print('Hello, World')`` instead of ``print 'Hello, World'``.

16046

+

16047

+

16048

+``from __future__ import unicode_literals``

16049

+'''''''''''''''''''''''''''''''''''''''''''

16050

+

16051

+Another personal choice. You can always mark what you want to be a (unicode)

16052

+string with a ``u`` prefix to get the same effect. But regardless of whether

16053

+you use this future statement or not, you **must** make sure you know exactly

16054

+which Python 2 strings you want to be bytes, and which are to be strings. This

16055

+means you should, **at minimum** mark all strings that are meant to be text

16056

+strings with a ``u`` prefix if you do not use this future statement.

16057

+

16058

+

16059

+Bytes literals

16060

+''''''''''''''

16061

+

16062

+This is a **very** important one. The ability to prefix Python 2 strings that

16063

+are meant to contain bytes with a ``b`` prefix help to very clearly delineate

16064

+what is and is not a Python 3 string. When you run 2to3 on code, all Python 2

16065

+strings become Python 3 strings **unless** they are prefixed with ``b``.

16066

+

16067

+There are some differences between byte literals in Python 2 and those in

16068

+Python 3 thanks to the bytes type just being an alias to ``str`` in Python 2.

16069

+Probably the biggest "gotcha" is that indexing results in different values. In

16070

+Python 2, the value of ``b'py'[1]`` is ``'y'``, while in Python 3 it's ``121``.

16071

+You can avoid this disparity by always slicing at the size of a single element:

16072

+``b'py'[1:2]`` is ``'y'`` in Python 2 and ``b'y'`` in Python 3 (i.e., close

16073

+enough).

16074

+

16075

+You cannot concatenate bytes and strings in Python 3. But since in Python

16076

+2 has bytes aliased to ``str``, it will succeed: ``b'a' + u'b'`` works in

16077

+Python 2, but ``b'a' + 'b'`` in Python 3 is a :exc:`TypeError`. A similar issue

16078

+also comes about when doing comparisons between bytes and strings.

16079

+

16080

+

16081

+Supporting `Python 2.5`_ and Newer Only

16082

+---------------------------------------

16083

+

16084

+If you are supporting `Python 2.5`_ and newer there are still some features of

16085

+Python that you can utilize.

16086

+

16087

+

16088

+``from __future__ import absolute_import``

16089

+''''''''''''''''''''''''''''''''''''''''''

16090

+

16091

+Implicit relative imports (e.g., importing ``spam.bacon`` from within

16092

+``spam.eggs`` with the statement ``import bacon``) does not work in Python 3.

16093

+This future statement moves away from that and allows the use of explicit

16094

+relative imports (e.g., ``from . import bacon``).

16095

+

16096

+In `Python 2.5`_ you must use

16097

+the __future__ statement to get to use explicit relative imports and prevent

16098

+implicit ones. In `Python 2.6`_ explicit relative imports are available without

16099

+the statement, but you still want the __future__ statement to prevent implicit

16100

+relative imports. In `Python 2.7`_ the __future__ statement is not needed. In

16101

+other words, unless you are only supporting Python 2.7 or a version earlier

16102

+than Python 2.5, use the __future__ statement.

16103

+

16104

+

16105

+

16106

+Handle Common "Gotchas"

16107

+-----------------------

16108

+

16109

+There are a few things that just consistently come up as sticking points for

16110

+people which 2to3 cannot handle automatically or can easily be done in Python 2

16111

+to help modernize your code.

16112

+

16113

+

16114

+``from __future__ import division``

16115

+'''''''''''''''''''''''''''''''''''

16116

+

16117

+While the exact same outcome can be had by using the ``-Qnew`` argument to

16118

+Python, using this future statement lifts the requirement that your users use

16119

+the flag to get the expected behavior of division in Python 3

16120

+(e.g., ``1/2 == 0.5; 1//2 == 0``).

16121

+

16122

+

16123

+

16124

+Specify when opening a file as binary

16125

+'''''''''''''''''''''''''''''''''''''

16126

+

16127

+Unless you have been working on Windows, there is a chance you have not always

16128

+bothered to add the ``b`` mode when opening a binary file (e.g., ``rb`` for

16129

+binary reading). Under Python 3, binary files and text files are clearly

16130

+distinct and mutually incompatible; see the :mod:`io` module for details.

16131

+Therefore, you **must** make a decision of whether a file will be used for

16132

+binary access (allowing to read and/or write bytes data) or text access

16133

+(allowing to read and/or write unicode data).

16134

+

16135

+Text files

16136

+''''''''''

16137

+

16138

+Text files created using ``open()`` under Python 2 return byte strings,

16139

+while under Python 3 they return unicode strings. Depending on your porting

16140

+strategy, this can be an issue.

16141

+

16142

+If you want text files to return unicode strings in Python 2, you have two

16143

+possibilities:

16144

+

16145

+* Under Python 2.6 and higher, use :func:`io.open`. Since :func:`io.open`

16146

+ is essentially the same function in both Python 2 and Python 3, it will

16147

+ help iron out any issues that might arise.

16148

+

16149

+* If pre-2.6 compatibility is needed, then you should use :func:`codecs.open`

16150

+ instead. This will make sure that you get back unicode strings in Python 2.

16151

+

16152

+Subclass ``object``

16153

+'''''''''''''''''''

16154

+

16155

+New-style classes have been around since `Python 2.2`_. You need to make sure

16156

+you are subclassing from ``object`` to avoid odd edge cases involving method

16157

+resolution order, etc. This continues to be totally valid in Python 3 (although

16158

+unneeded as all classes implicitly inherit from ``object``).

16159

+

16160

+

16161

+Deal With the Bytes/String Dichotomy

16162

+''''''''''''''''''''''''''''''''''''

16163

+

16164

+One of the biggest issues people have when porting code to Python 3 is handling

16165

+the bytes/string dichotomy. Because Python 2 allowed the ``str`` type to hold

16166

+textual data, people have over the years been rather loose in their delineation

16167

+of what ``str`` instances held text compared to bytes. In Python 3 you cannot

16168

+be so care-free anymore and need to properly handle the difference. The key

16169

+handling this issue to make sure that **every** string literal in your

16170

+Python 2 code is either syntactically of functionally marked as either bytes or

16171

+text data. After this is done you then need to make sure your APIs are designed

16172

+to either handle a specific type or made to be properly polymorphic.

16173

+

16174

+

16175

+Mark Up Python 2 String Literals

16176

+********************************

16177

+

16178

+First thing you must do is designate every single string literal in Python 2

16179

+as either textual or bytes data. If you are only supporting Python 2.6 or

16180

+newer, this can be accomplished by marking bytes literals with a ``b`` prefix

16181

+and then designating textual data with a ``u`` prefix or using the

16182

+``unicode_literals`` future statement.

16183

+

16184

+If your project supports versions of Python pre-dating 2.6, then you should use

16185

+the six_ project and its ``b()`` function to denote bytes literals. For text

16186

+literals you can either use six's ``u()`` function or use a ``u`` prefix.

16187

+

16188

+

16189

+Decide what APIs Will Accept

16190

+****************************

16191

+

16192

+In Python 2 it was very easy to accidentally create an API that accepted both

16193

+bytes and textual data. But in Python 3, thanks to the more strict handling of

16194

+disparate types, this loose usage of bytes and text together tends to fail.

16195

+

16196

+Take the dict ``{b'a': 'bytes', u'a': 'text'}`` in Python 2.6. It creates the

16197

+dict ``{u'a': 'text'}`` since ``b'a' == u'a'``. But in Python 3 the equivalent

16198

+dict creates ``{b'a': 'bytes', 'a': 'text'}``, i.e., no lost data. Similar

16199

+issues can crop up when transitioning Python 2 code to Python 3.

16200

+

16201

+This means you need to choose what an API is going to accept and create and

16202

+consistently stick to that API in both Python 2 and 3.

16203

+

16204

+

16205

+Bytes / Unicode Comparison

16206

+**************************

16207

+

16208

+In Python 3, mixing bytes and unicode is forbidden in most situations; it

16209

+will raise a :class:`TypeError` where Python 2 would have attempted an implicit

16210

+coercion between types. However, there is one case where it doesn't and

16211

+it can be very misleading::

16212

+

16213

+ >>> b"" == ""

16214

+ False

16215

+

16216

+This is because an equality comparison is required by the language to always

16217

+succeed (and return ``False`` for incompatible types). However, this also

16218

+means that code incorrectly ported to Python 3 can display buggy behaviour

16219

+if such comparisons are silently executed. To detect such situations,

16220

+Python 3 has a ``-b`` flag that will display a warning::

16221

+

16222

+ $ python3 -b

16223

+ >>> b"" == ""

16224

+ __main__:1: BytesWarning: Comparison between bytes and string

16225

+ False

16226

+

16227

+To turn the warning into an exception, use the ``-bb`` flag instead::

16228

+

16229

+ $ python3 -bb

16230

+ >>> b"" == ""

16231

+ Traceback (most recent call last):

16232

+ File "<stdin>", line 1, in <module>

16233

+ BytesWarning: Comparison between bytes and string

16234

+

16235

+

16236

+Indexing bytes objects

16237

+''''''''''''''''''''''

16238

+

16239

+Another potentially surprising change is the indexing behaviour of bytes

16240

+objects in Python 3::

16241

+

16242

+ >>> b"xyz"[0]

16243

+ 120

16244

+

16245

+Indeed, Python 3 bytes objects (as well as :class:`bytearray` objects)

16246

+are sequences of integers. But code converted from Python 2 will often

16247

+assume that indexing a bytestring produces another bytestring, not an

16248

+integer. To reconcile both behaviours, use slicing::

16249

+

16250

+ >>> b"xyz"[0:1]

16251

+ b'x'

16252

+ >>> n = 1

16253

+ >>> b"xyz"[n:n+1]

16254

+ b'y'

16255

+

16256

+The only remaining gotcha is that an out-of-bounds slice returns an empty

16257

+bytes object instead of raising ``IndexError``:

16258

+

16259

+ >>> b"xyz"[3]

16260

+ Traceback (most recent call last):

16261

+ File "<stdin>", line 1, in <module>

16262

+ IndexError: index out of range

16263

+ >>> b"xyz"[3:4]

16264

+ b''

16265

+

16266

+

16267

+``__str__()``/``__unicode__()``

16268

+'''''''''''''''''''''''''''''''

16269

+

16270

+In Python 2, objects can specify both a string and unicode representation of

16271

+themselves. In Python 3, though, there is only a string representation. This

16272

+becomes an issue as people can inadvertently do things in their ``__str__()``

16273

+methods which have unpredictable results (e.g., infinite recursion if you

16274

+happen to use the ``unicode(self).encode('utf8')`` idiom as the body of your

16275

+``__str__()`` method).

16276

+

16277

+There are two ways to solve this issue. One is to use a custom 2to3 fixer. The

16278

+blog post at http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/

16279

+specifies how to do this. That will allow 2to3 to change all instances of ``def

16280

+__unicode(self): ...`` to ``def __str__(self): ...``. This does require you

16281

+define your ``__str__()`` method in Python 2 before your ``__unicode__()``

16282

+method.

16283

+

16284

+The other option is to use a mixin class. This allows you to only define a

16285

+``__unicode__()`` method for your class and let the mixin derive

16286

+``__str__()`` for you (code from

16287

+http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/)::

16288

+

16289

+ import sys

16290

+

16291

+ class UnicodeMixin(object):

16292

+

16293

+ """Mixin class to handle defining the proper __str__/__unicode__

16294

+ methods in Python 2 or 3."""

16295

+

16296

+ if sys.version_info[0] >= 3: # Python 3

16297

+ def __str__(self):

16298

+ return self.__unicode__()

16299

+ else: # Python 2

16300

+ def __str__(self):

16301

+ return self.__unicode__().encode('utf8')

16302

+

16303

+

16304

+ class Spam(UnicodeMixin):

16305

+

16306

+ def __unicode__(self):

16307

+ return u'spam-spam-bacon-spam' # 2to3 will remove the 'u' prefix

16308

+

16309

+

16310

+Don't Index on Exceptions

16311

+'''''''''''''''''''''''''

16312

+

16313

+In Python 2, the following worked::

16314

+

16315

+ >>> exc = Exception(1, 2, 3)

16316

+ >>> exc.args[1]

16317

+ 2

16318

+ >>> exc[1] # Python 2 only!

16319

+ 2

16320

+

16321

+But in Python 3, indexing directly on an exception is an error. You need to

16322

+make sure to only index on the :attr:`BaseException.args` attribute which is a

16323

+sequence containing all arguments passed to the :meth:`__init__` method.

16324

+

16325

+Even better is to use the documented attributes the exception provides.

16326

+

16327

+Don't use ``__getslice__`` & Friends

16328

+''''''''''''''''''''''''''''''''''''

16329

+

16330

+Been deprecated for a while, but Python 3 finally drops support for

16331

+``__getslice__()``, etc. Move completely over to :meth:`__getitem__` and

16332

+friends.

16333

+

16334

+

16335

+Updating doctests

16336

+'''''''''''''''''

16337

+

16338

+2to3_ will attempt to generate fixes for doctests that it comes across. It's

16339

+not perfect, though. If you wrote a monolithic set of doctests (e.g., a single

16340

+docstring containing all of your doctests), you should at least consider

16341

+breaking the doctests up into smaller pieces to make it more manageable to fix.

16342

+Otherwise it might very well be worth your time and effort to port your tests

16343

+to :mod:`unittest`.

16344

+

16345

+

16346

+Eliminate ``-3`` Warnings

16347

+-------------------------

16348

+

16349

+When you run your application's test suite, run it using the ``-3`` flag passed

16350

+to Python. This will cause various warnings to be raised during execution about

16351

+things that 2to3 cannot handle automatically (e.g., modules that have been

16352

+removed). Try to eliminate those warnings to make your code even more portable

16353

+to Python 3.

16354

+

16355

+

16356

+Run 2to3

16357

+--------

16358

+

16359

+Once you have made your Python 2 code future-compatible with Python 3, it's

16360

+time to use 2to3_ to actually port your code.

16361

+

16362

+

16363

+Manually

16364

+''''''''

16365

+

16366

+To manually convert source code using 2to3_, you use the ``2to3`` script that

16367

+is installed with Python 2.6 and later.::

16368

+

16369

+ 2to3 <directory or file to convert>

16370

+

16371

+This will cause 2to3 to write out a diff with all of the fixers applied for the

16372

+converted source code. If you would like 2to3 to go ahead and apply the changes

16373

+you can pass it the ``-w`` flag::

16374

+

16375

+ 2to3 -w <stuff to convert>

16376

+

16377

+There are other flags available to control exactly which fixers are applied,

16378

+etc.

16379

+

16380

+

16381

+During Installation

16382

+'''''''''''''''''''

16383

+

16384

+When a user installs your project for Python 3, you can have either

16385

+:mod:`distutils` or Distribute_ run 2to3_ on your behalf.

16386

+For distutils, use the following idiom::

16387

+

16388

+ try: # Python 3

16389

+ from distutils.command.build_py import build_py_2to3 as build_py

16390

+ except ImportError: # Python 2

16391

+ from distutils.command.build_py import build_py

16392

+

16393

+ setup(cmdclass = {'build_py': build_py},

16394

+ # ...

16395

+ )

16396

+

16397

+For Distribute::

16398

+

16399

+ setup(use_2to3=True,

16400

+ # ...

16401

+ )

16402

+

16403

+This will allow you to not have to distribute a separate Python 3 version of

16404

+your project. It does require, though, that when you perform development that

16405

+you at least build your project and use the built Python 3 source for testing.

16406

+

16407

+

16408

+Verify & Test

16409

+-------------

16410

+

16411

+At this point you should (hopefully) have your project converted in such a way

16412

+that it works in Python 3. Verify it by running your unit tests and making sure

16413

+nothing has gone awry. If you miss something then figure out how to fix it in

16414

+Python 3, backport to your Python 2 code, and run your code through 2to3 again

16415

+to verify the fix transforms properly.

16416

+

16417

+

16418

+.. _2to3: http://docs.python.org/py3k/library/2to3.html

16419

+.. _Distribute: http://packages.python.org/distribute/

16420

+

16421

+

16422

+.. _use_same_source:

16423

+

16424

+Python 2/3 Compatible Source

16425

+============================

16426

+

16427

+While it may seem counter-intuitive, you can write Python code which is

16428

+source-compatible between Python 2 & 3. It does lead to code that is not

16429

+entirely idiomatic Python (e.g., having to extract the currently raised

16430

+exception from ``sys.exc_info()[1]``), but it can be run under Python 2

16431

+**and** Python 3 without using 2to3_ as a translation step (although the tool

16432

+should be used to help find potential portability problems). This allows you to

16433

+continue to have a rapid development process regardless of whether you are

16434

+developing under Python 2 or Python 3. Whether this approach or using

16435

+:ref:`use_2to3` works best for you will be a per-project decision.

16436

+

16437

+To get a complete idea of what issues you will need to deal with, see the

16438

+`What's New in Python 3.0`_. Others have reorganized the data in other formats

16439

+such as http://docs.pythonsprints.com/python3_porting/py-porting.html .

16440

+

16441

+The following are some steps to take to try to support both Python 2 & 3 from

16442

+the same source code.

16443

+

16444

+

16445

+.. _What's New in Python 3.0: http://docs.python.org/release/3.0/whatsnew/3.0.html

16446

+

16447

+

16448

+Follow The Steps for Using 2to3_

16449

+--------------------------------

16450

+

16451

+All of the steps outlined in how to

16452

+:ref:`port Python 2 code with 2to3 <use_2to3>` apply

16453

+to creating a Python 2/3 codebase. This includes trying only support Python 2.6

16454

+or newer (the :mod:`__future__` statements work in Python 3 without issue),

16455

+eliminating warnings that are triggered by ``-3``, etc.

16456

+

16457

+You should even consider running 2to3_ over your code (without committing the

16458

+changes). This will let you know where potential pain points are within your

16459

+code so that you can fix them properly before they become an issue.

16460

+

16461

+

16462

+Use six_

16463

+--------

16464

+

16465

+The six_ project contains many things to help you write portable Python code.

16466

+You should make sure to read its documentation from beginning to end and use

16467

+any and all features it provides. That way you will minimize any mistakes you

16468

+might make in writing cross-version code.

16469

+

16470

+

16471

+Capturing the Currently Raised Exception

16472

+----------------------------------------

16473

+

16474

+One change between Python 2 and 3 that will require changing how you code (if

16475

+you support `Python 2.5`_ and earlier) is

16476

+accessing the currently raised exception. In Python 2.5 and earlier the syntax

16477

+to access the current exception is::

16478

+

16479

+ try:

16480

+ raise Exception()

16481

+ except Exception, exc:

16482

+ # Current exception is 'exc'

16483

+ pass

16484

+

16485

+This syntax changed in Python 3 (and backported to `Python 2.6`_ and later)

16486

+to::

16487

+

16488

+ try:

16489

+ raise Exception()

16490

+ except Exception as exc:

16491

+ # Current exception is 'exc'

16492

+ # In Python 3, 'exc' is restricted to the block; Python 2.6 will "leak"

16493

+ pass

16494

+

16495

+Because of this syntax change you must change to capturing the current

16496

+exception to::

16497

+

16498

+ try:

16499

+ raise Exception()

16500

+ except Exception:

16501

+ import sys

16502

+ exc = sys.exc_info()[1]

16503

+ # Current exception is 'exc'

16504

+ pass

16505

+

16506

+You can get more information about the raised exception from

16507

+:func:`sys.exc_info` than simply the current exception instance, but you most

16508

+likely don't need it.

16509

+

16510

+.. note::

16511

+ In Python 3, the traceback is attached to the exception instance

16512

+ through the ``__traceback__`` attribute. If the instance is saved in

16513

+ a local variable that persists outside of the ``except`` block, the

16514

+ traceback will create a reference cycle with the current frame and its

16515

+ dictionary of local variables. This will delay reclaiming dead

16516

+ resources until the next cyclic :term:`garbage collection` pass.

16517

+

16518

+ In Python 2, this problem only occurs if you save the traceback itself

16519

+ (e.g. the third element of the tuple returned by :func:`sys.exc_info`)

16520

+ in a variable.

16521

+

16522

+

16523

+Other Resources

16524

+===============

16525

+

16526

+The authors of the following blog posts, wiki pages, and books deserve special

16527

+thanks for making public their tips for porting Python 2 code to Python 3 (and

16528

+thus helping provide information for this document):

16529

+

16530

+* http://python3porting.com/

16531

+* http://docs.pythonsprints.com/python3_porting/py-porting.html

16532

+* http://techspot.zzzeek.org/2011/01/24/zzzeek-s-guide-to-python-3-porting/

16533

+* http://dabeaz.blogspot.com/2011/01/porting-py65-and-my-superboard-to.html

16534

+* http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/

16535

+* http://lucumr.pocoo.org/2010/2/11/porting-to-python-3-a-guide/

16536

+* http://wiki.python.org/moin/PortingPythonToPy3k

16537

+

16538

+If you feel there is something missing from this document that should be added,

16539

+please email the python-porting_ mailing list.

16540

+

16541

+.. _python-porting: http://mail.python.org/mailman/listinfo/python-porting

16542

diff -r 8527427914a2 Doc/howto/sockets.rst

16543

--- a/Doc/howto/sockets.rst

16544

+++ b/Doc/howto/sockets.rst

16545

@@ -1,3 +1,5 @@

16546

+.. _socket-howto:

16547

+

16548

****************************

16549

Socket Programming HOWTO

16550

****************************

16551

diff -r 8527427914a2 Doc/howto/sorting.rst

16552

--- a/Doc/howto/sorting.rst

16553

+++ b/Doc/howto/sorting.rst

16554

@@ -111,6 +111,15 @@

16555

>>> sorted(student_objects, key=attrgetter('grade', 'age'))

16556

[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]

16557

16558

+The :func:`operator.methodcaller` function makes method calls with fixed

16559

+parameters for each object being sorted. For example, the :meth:`str.count`

16560

+method could be used to compute message priority by counting the

16561

+number of exclamation marks in a message:

16562

+

16563

+ >>> messages = ['critical!!!', 'hurry!', 'standby', 'immediate!!']

16564

+ >>> sorted(messages, key=methodcaller('count', '!'))

16565

+ ['standby', 'hurry!', 'immediate!!', 'critical!!!']

16566

+

16567

Ascending and Descending

16568

========================

16569

16570

@@ -259,28 +268,36 @@

16571

* For locale aware sorting, use :func:`locale.strxfrm` for a key function or

16572

:func:`locale.strcoll` for a comparison function.

16573

16574

-* The *reverse* parameter still maintains sort stability (i.e. records with

16575

- equal keys retain the original order). Interestingly, that effect can be

16576

+* The *reverse* parameter still maintains sort stability (so that records with

16577

+ equal keys retain their original order). Interestingly, that effect can be

16578

simulated without the parameter by using the builtin :func:`reversed` function

16579

twice:

16580

16581

>>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]

16582

>>> assert sorted(data, reverse=True) == list(reversed(sorted(reversed(data))))

16583

16584

-* The sort routines are guaranteed to use :meth:`__lt__` when making comparisons

16585

- between two objects. So, it is easy to add a standard sort order to a class by

16586

- defining an :meth:`__lt__` method::

16587

+* To create a standard sort order for a class, just add the appropriate rich

16588

+ comparison methods:

16589

16590

+ >>> Student.__eq__ = lambda self, other: self.age == other.age

16591

+ >>> Student.__ne__ = lambda self, other: self.age != other.age

16592

>>> Student.__lt__ = lambda self, other: self.age < other.age

16593

+ >>> Student.__le__ = lambda self, other: self.age <= other.age

16594

+ >>> Student.__gt__ = lambda self, other: self.age > other.age

16595

+ >>> Student.__ge__ = lambda self, other: self.age >= other.age

16596

>>> sorted(student_objects)

16597

[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

16598

16599

+ For general purpose comparisons, the recommended approach is to define all six

16600

+ rich comparison operators. The :func:`functools.total_ordering` class

16601

+ decorator makes this easy to implement.

16602

+

16603

* Key functions need not depend directly on the objects being sorted. A key

16604

function can also access external resources. For instance, if the student grades

16605

are stored in a dictionary, they can be used to sort a separate list of student

16606

names:

16607

16608

>>> students = ['dave', 'john', 'jane']

16609

- >>> newgrades = {'john': 'F', 'jane':'A', 'dave': 'C'}

16610

- >>> sorted(students, key=newgrades.__getitem__)

16611

+ >>> grades = {'john': 'F', 'jane':'A', 'dave': 'C'}

16612

+ >>> sorted(students, key=grades.__getitem__)

16613

['jane', 'dave', 'john']

16614

diff -r 8527427914a2 Doc/howto/urllib2.rst

16615

--- a/Doc/howto/urllib2.rst

16616

+++ b/Doc/howto/urllib2.rst

16617

@@ -138,7 +138,7 @@

16618

name=Somebody+Here&language=Python&location=Northampton

16619

>>> url = 'http://www.example.com/example.cgi'

16620

>>> full_url = url + '?' + url_values

16621

- >>> data = urllib2.open(full_url)

16622

+ >>> data = urllib2.urlopen(full_url)

16623

16624

Notice that the full URL is created by adding a ``?`` to the URL, followed by

16625

the encoded values.

16626

diff -r 8527427914a2 Doc/howto/webservers.rst

16627

--- a/Doc/howto/webservers.rst

16628

+++ b/Doc/howto/webservers.rst

16629

@@ -264,7 +264,7 @@

16630

16631

* `FastCGI, SCGI, and Apache: Background and Future

16632

<http://www.vmunix.com/mark/blog/archives/2006/01/02/fastcgi-scgi-and-apache-background-and-future/>`_

16633

- is a discussion on why the concept of FastCGI and SCGI is better that that

16634

+ is a discussion on why the concept of FastCGI and SCGI is better than that

16635

of mod_python.

16636

16637

16638

@@ -274,7 +274,7 @@

16639

Each web server requires a specific module.

16640

16641

* Apache has both `mod_fastcgi <http://www.fastcgi.com/drupal/>`_ and `mod_fcgid

16642

- <http://fastcgi.coremail.cn/>`_. ``mod_fastcgi`` is the original one, but it

16643

+ <http://httpd.apache.org/mod_fcgid/>`_. ``mod_fastcgi`` is the original one, but it

16644

has some licensing issues, which is why it is sometimes considered non-free.

16645

``mod_fcgid`` is a smaller, compatible alternative. One of these modules needs

16646

to be loaded by Apache.

16647

@@ -364,7 +364,7 @@

16648

16649

A really great WSGI feature is middleware. Middleware is a layer around your

16650

program which can add various functionality to it. There is quite a bit of

16651

-`middleware <http://wsgi.org/wsgi/Middleware_and_Utilities>`_ already

16652

+`middleware <http://www.wsgi.org/en/latest/libraries.html>`_ already

16653

available. For example, instead of writing your own session management (HTTP

16654

is a stateless protocol, so to associate multiple HTTP requests with a single

16655

user your application must create and manage such state via a session), you can

16656

@@ -395,9 +395,9 @@

16657

16658

.. seealso::

16659

16660

- A good overview of WSGI-related code can be found in the `WSGI wiki

16661

- <http://wsgi.org/wsgi>`_, which contains an extensive list of `WSGI servers

16662

- <http://wsgi.org/wsgi/Servers>`_ which can be used by *any* application

16663

+ A good overview of WSGI-related code can be found in the `WSGI homepage

16664

+ <http://www.wsgi.org/en/latest/index.html>`_, which contains an extensive list of `WSGI servers

16665

+ <http://www.wsgi.org/en/latest/servers.html>`_ which can be used by *any* application

16666

supporting WSGI.

16667

16668

You might be interested in some WSGI-supporting modules already contained in

16669

diff -r 8527427914a2 Doc/includes/capsulethunk.h

16670

--- /dev/null

16671

+++ b/Doc/includes/capsulethunk.h

16672

@@ -0,0 +1,134 @@

16673

+#ifndef __CAPSULETHUNK_H

16674

+#define __CAPSULETHUNK_H

16675

+

16676

+#if ( (PY_VERSION_HEX < 0x02070000) \

16677

+ || ((PY_VERSION_HEX >= 0x03000000) \

16678

+ && (PY_VERSION_HEX < 0x03010000)) )

16679

+

16680

+#define __PyCapsule_GetField(capsule, field, default_value) \

16681

+ ( PyCapsule_CheckExact(capsule) \

16682

+ ? (((PyCObject *)capsule)->field) \

16683

+ : (default_value) \

16684

+ ) \

16685

+

16686

+#define __PyCapsule_SetField(capsule, field, value) \

16687

+ ( PyCapsule_CheckExact(capsule) \

16688

+ ? (((PyCObject *)capsule)->field = value), 1 \

16689

+ : 0 \

16690

+ ) \

16691

+

16692

+

16693

+#define PyCapsule_Type PyCObject_Type

16694

+

16695

+#define PyCapsule_CheckExact(capsule) (PyCObject_Check(capsule))

16696

+#define PyCapsule_IsValid(capsule, name) (PyCObject_Check(capsule))

16697

+

16698

+

16699

+#define PyCapsule_New(pointer, name, destructor) \

16700

+ (PyCObject_FromVoidPtr(pointer, destructor))

16701

+

16702

+

16703

+#define PyCapsule_GetPointer(capsule, name) \

16704

+ (PyCObject_AsVoidPtr(capsule))

16705

+

16706

+/* Don't call PyCObject_SetPointer here, it fails if there's a destructor */

16707

+#define PyCapsule_SetPointer(capsule, pointer) \

16708

+ __PyCapsule_SetField(capsule, cobject, pointer)

16709

+

16710

+

16711

+#define PyCapsule_GetDestructor(capsule) \

16712

+ __PyCapsule_GetField(capsule, destructor)

16713

+

16714

+#define PyCapsule_SetDestructor(capsule, dtor) \

16715

+ __PyCapsule_SetField(capsule, destructor, dtor)

16716

+

16717

+

16718

+/*

16719

+ * Sorry, there's simply no place

16720

+ * to store a Capsule "name" in a CObject.

16721

+ */

16722

+#define PyCapsule_GetName(capsule) NULL

16723

+

16724

+static int

16725

+PyCapsule_SetName(PyObject *capsule, const char *unused)

16726

+{

16727

+ unused = unused;

16728

+ PyErr_SetString(PyExc_NotImplementedError,

16729

+ "can't use PyCapsule_SetName with CObjects");

16730

+ return 1;

16731

+}

16732

+

16733

+

16734

+

16735

+#define PyCapsule_GetContext(capsule) \

16736

+ __PyCapsule_GetField(capsule, descr)

16737

+

16738

+#define PyCapsule_SetContext(capsule, context) \

16739

+ __PyCapsule_SetField(capsule, descr, context)

16740

+

16741

+

16742

+static void *

16743

+PyCapsule_Import(const char *name, int no_block)

16744

+{

16745

+ PyObject *object = NULL;

16746

+ void *return_value = NULL;

16747

+ char *trace;

16748

+ size_t name_length = (strlen(name) + 1) * sizeof(char);

16749

+ char *name_dup = (char *)PyMem_MALLOC(name_length);

16750

+

16751

+ if (!name_dup) {

16752

+ return NULL;

16753

+ }

16754

+

16755

+ memcpy(name_dup, name, name_length);

16756

+

16757

+ trace = name_dup;

16758

+ while (trace) {

16759

+ char *dot = strchr(trace, '.');

16760

+ if (dot) {

16761

+ *dot++ = '\0';

16762

+ }

16763

+

16764

+ if (object == NULL) {

16765

+ if (no_block) {

16766

+ object = PyImport_ImportModuleNoBlock(trace);

16767

+ } else {

16768

+ object = PyImport_ImportModule(trace);

16769

+ if (!object) {

16770

+ PyErr_Format(PyExc_ImportError,

16771

+ "PyCapsule_Import could not "

16772

+ "import module \"%s\"", trace);

16773

+ }

16774

+ }

16775

+ } else {

16776

+ PyObject *object2 = PyObject_GetAttrString(object, trace);

16777

+ Py_DECREF(object);

16778

+ object = object2;

16779

+ }

16780

+ if (!object) {

16781

+ goto EXIT;

16782

+ }

16783

+

16784

+ trace = dot;

16785

+ }

16786

+

16787

+ if (PyCObject_Check(object)) {

16788

+ PyCObject *cobject = (PyCObject *)object;

16789

+ return_value = cobject->cobject;

16790

+ } else {

16791

+ PyErr_Format(PyExc_AttributeError,

16792

+ "PyCapsule_Import \"%s\" is not valid",

16793

+ name);

16794

+ }

16795

+

16796

+EXIT:

16797

+ Py_XDECREF(object);

16798

+ if (name_dup) {

16799

+ PyMem_FREE(name_dup);

16800

+ }

16801

+ return return_value;

16802

+}

16803

+

16804

+#endif /* #if PY_VERSION_HEX < 0x02070000 */

16805

+

16806

+#endif /* __CAPSULETHUNK_H */

16807

diff -r 8527427914a2 Doc/includes/sqlite3/ctx_manager.py

16808

--- a/Doc/includes/sqlite3/ctx_manager.py

16809

+++ b/Doc/includes/sqlite3/ctx_manager.py

16810

@@ -8,7 +8,7 @@

16811

con.execute("insert into person(firstname) values (?)", ("Joe",))

16812

16813

# con.rollback() is called after the with block finishes with an exception, the

16814

-# exception is still raised and must be catched

16815

+# exception is still raised and must be caught

16816

try:

16817

with con:

16818

con.execute("insert into person(firstname) values (?)", ("Joe",))

16819

diff -r 8527427914a2 Doc/install/index.rst

16820

--- a/Doc/install/index.rst

16821

+++ b/Doc/install/index.rst

16822

@@ -72,7 +72,7 @@

16823

do the obvious thing with it: run it if it's an executable installer, ``rpm

16824

--install`` it if it's an RPM, etc. You don't need to run Python or a setup

16825

script, you don't need to compile anything---you might not even need to read any

16826

-instructions (although it's always a good idea to do so anyways).

16827

+instructions (although it's always a good idea to do so anyway).

16828

16829

Of course, things will not always be that easy. You might be interested in a

16830

module distribution that doesn't have an easy-to-use installer for your

16831

@@ -96,10 +96,16 @@

16832

directory: :file:`foo-1.0` or :file:`widget-0.9.7`. Additionally, the

16833

distribution will contain a setup script :file:`setup.py`, and a file named

16834

:file:`README.txt` or possibly just :file:`README`, which should explain that

16835

-building and installing the module distribution is a simple matter of running ::

16836

+building and installing the module distribution is a simple matter of running

16837

+one command from a terminal::

16838

16839

python setup.py install

16840

16841

+For Windows, this command should be run from a command prompt window

16842

+(:menuselection:`Start --> Accessories`)::

16843

+

16844

+ setup.py install

16845

+

16846

If all these things are true, then you already know how to build and install the

16847

modules you've just downloaded: Run the command above. Unless you need to

16848

install things in a non-standard way or customize the build process, you don't

16849

@@ -113,14 +119,11 @@

16850

==========================

16851

16852

As described in section :ref:`inst-new-standard`, building and installing a module

16853

-distribution using the Distutils is usually one simple command::

16854

+distribution using the Distutils is usually one simple command to run from a

16855

+terminal::

16856

16857

python setup.py install

16858

16859

-On Unix, you'd run this command from a shell prompt; on Windows, you have to

16860

-open a command prompt window ("DOS box") and do it there; on Mac OS X, you open

16861

-a :command:`Terminal` window to get a shell prompt.

16862

-

16863

16864

.. _inst-platform-variations:

16865

16866

@@ -141,7 +144,7 @@

16867

:file:`C:\\Temp\\foo-1.0`; you can use either a archive manipulator with a

16868

graphical user interface (such as WinZip) or a command-line tool (such as

16869

:program:`unzip` or :program:`pkunzip`) to unpack the archive. Then, open a

16870

-command prompt window ("DOS box"), and run::

16871

+command prompt window and run::

16872

16873

cd c:\Temp\foo-1.0

16874

python setup.py install

16875

@@ -276,6 +279,12 @@

16876

>>> sys.exec_prefix

16877

'/usr'

16878

16879

+A few other placeholders are used in this document: :file:`{X.Y}` stands for the

16880

+version of Python, for example ``2.7``; :file:`{distname}` will be replaced by

16881

+the name of the module distribution being installed. Dots and capitalization

16882

+are important in the paths; for example, a value that uses ``python2.7`` on UNIX

16883

+will typically use ``Python27`` on Windows.

16884

+

16885

If you don't want to install modules to the standard location, or if you don't

16886

have permission to write there, then you need to read about alternate

16887

installations in section :ref:`inst-alt-install`. If you want to customize your

16888

@@ -304,8 +313,61 @@

16889

differ across platforms, so read whichever of the following sections applies to

16890

you.

16891

16892

+Note that the various alternate installation schemes are mutually exclusive: you

16893

+can pass ``--user``, or ``--home``, or ``--prefix`` and ``--exec-prefix``, or

16894

+``--install-base`` and ``--install-platbase``, but you can't mix from these

16895

+groups.

16896

16897

-.. _inst-alt-install-prefix:

16898

+

16899

+.. _inst-alt-install-user:

16900

+

16901

+Alternate installation: the user scheme

16902

+---------------------------------------

16903

+

16904

+This scheme is designed to be the most convenient solution for users that don't

16905

+have write permission to the global site-packages directory or don't want to

16906

+install into it. It is enabled with a simple option::

16907

+

16908

+ python setup.py install --user

16909

+

16910

+Files will be installed into subdirectories of :data:`site.USER_BASE` (written

16911

+as :file:`{userbase}` hereafter). This scheme installs pure Python modules and

16912

+extension modules in the same location (also known as :data:`site.USER_SITE`).

16913

+Here are the values for UNIX, including Mac OS X:

16914

+

16915

+=============== ===========================================================

16916

+Type of file Installation directory

16917

+=============== ===========================================================

16918

+modules :file:`{userbase}/lib/python{X.Y}/site-packages`

16919

+scripts :file:`{userbase}/bin`

16920

+data :file:`{userbase}`

16921

+C headers :file:`{userbase}/include/python{X.Y}/{distname}`

16922

+=============== ===========================================================

16923

+

16924

+And here are the values used on Windows:

16925

+

16926

+=============== ===========================================================

16927

+Type of file Installation directory

16928

+=============== ===========================================================

16929

+modules :file:`{userbase}\\Python{XY}\\site-packages`

16930

+scripts :file:`{userbase}\\Scripts`

16931

+data :file:`{userbase}`

16932

+C headers :file:`{userbase}\\Python{XY}\\Include\\{distname}`

16933

+=============== ===========================================================

16934

+

16935

+The advantage of using this scheme compared to the other ones described below is

16936

+that the user site-packages directory is under normal conditions always included

16937

+in :data:`sys.path` (see :mod:`site` for more information), which means that

16938

+there is no additional step to perform after running the :file:`setup.py` script

16939

+to finalize the installation.

16940

+

16941

+The :command:`build_ext` command also has a ``--user`` option to add

16942

+:file:`{userbase}/include` to the compiler search path for header files and

16943

+:file:`{userbase}/lib` to the compiler search path for libraries as well as to

16944

+the runtime search path for shared C libraries (rpath).

16945

+

16946

+

16947

+.. _inst-alt-install-home:

16948

16949

Alternate installation: the home scheme

16950

---------------------------------------

16951

@@ -327,26 +389,30 @@

16952

16953

python setup.py install --home=~

16954

16955

+To make Python find the distributions installed with this scheme, you may have

16956

+to :ref:`modify Python's search path <inst-search-path>` or edit

16957

+:mod:`sitecustomize` (see :mod:`site`) to call :func:`site.addsitedir` or edit

16958

+:data:`sys.path`.

16959

+

16960

The :option:`--home` option defines the installation base directory. Files are

16961

installed to the following directories under the installation base as follows:

16962

16963

-+------------------------------+---------------------------+-----------------------------+

16964

-| Type of file | Installation Directory | Override option |

16965

-+==============================+===========================+=============================+

16966

-| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` |

16967

-+------------------------------+---------------------------+-----------------------------+

16968

-| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` |

16969

-+------------------------------+---------------------------+-----------------------------+

16970

-| scripts | :file:`{home}/bin` | :option:`--install-scripts` |

16971

-+------------------------------+---------------------------+-----------------------------+

16972

-| data | :file:`{home}/share` | :option:`--install-data` |

16973

-+------------------------------+---------------------------+-----------------------------+

16974

+=============== ===========================================================

16975

+Type of file Installation directory

16976

+=============== ===========================================================

16977

+modules :file:`{home}/lib/python`

16978

+scripts :file:`{home}/bin`

16979

+data :file:`{home}`

16980

+C headers :file:`{home}/include/python/{distname}`

16981

+=============== ===========================================================

16982

+

16983

+(Mentally replace slashes with backslashes if you're on Windows.)

16984

16985

.. versionchanged:: 2.4

16986

The :option:`--home` option used to be supported only on Unix.

16987

16988

16989

-.. _inst-alt-install-home:

16990

+.. _inst-alt-install-prefix-unix:

16991

16992

Alternate installation: Unix (the prefix scheme)

16993

------------------------------------------------

16994

@@ -355,7 +421,7 @@

16995

perform the build/install (i.e., to run the setup script), but install modules

16996

into the third-party module directory of a different Python installation (or

16997

something that looks like a different Python installation). If this sounds a

16998

-trifle unusual, it is---that's why the "home scheme" comes first. However,

16999

+trifle unusual, it is---that's why the user and home schemes come before. However,

17000

there are at least two known cases where the prefix scheme will be useful.

17001

17002

First, consider that many Linux distributions put Python in :file:`/usr`, rather

17003

@@ -383,17 +449,15 @@

17004

executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to

17005

:option:`--prefix`. Files are installed as follows:

17006

17007

-+------------------------------+-----------------------------------------------------+-----------------------------+

17008

-| Type of file | Installation Directory | Override option |

17009

-+==============================+=====================================================+=============================+

17010

-| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` |

17011

-+------------------------------+-----------------------------------------------------+-----------------------------+

17012

-| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` |

17013

-+------------------------------+-----------------------------------------------------+-----------------------------+

17014

-| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` |

17015

-+------------------------------+-----------------------------------------------------+-----------------------------+

17016

-| data | :file:`{prefix}/share` | :option:`--install-data` |

17017

-+------------------------------+-----------------------------------------------------+-----------------------------+

17018

+================= ==========================================================

17019

+Type of file Installation directory

17020

+================= ==========================================================

17021

+Python modules :file:`{prefix}/lib/python{X.Y}/site-packages`

17022

+extension modules :file:`{exec-prefix}/lib/python{X.Y}/site-packages`

17023

+scripts :file:`{prefix}/bin`

17024

+data :file:`{prefix}`

17025

+C headers :file:`{prefix}/include/python{X.Y}/{distname}`

17026

+================= ==========================================================

17027

17028

There is no requirement that :option:`--prefix` or :option:`--exec-prefix`

17029

actually point to an alternate Python installation; if the directories listed

17030

@@ -418,7 +482,7 @@

17031

alternate Python installation, this is immaterial.)

17032

17033

17034

-.. _inst-alt-install-windows:

17035

+.. _inst-alt-install-prefix-windows:

17036

17037

Alternate installation: Windows (the prefix scheme)

17038

---------------------------------------------------

17039

@@ -433,20 +497,18 @@

17040

to install modules to the :file:`\\Temp\\Python` directory on the current drive.

17041

17042

The installation base is defined by the :option:`--prefix` option; the

17043

-:option:`--exec-prefix` option is not supported under Windows. Files are

17044

-installed as follows:

17045

+:option:`--exec-prefix` option is not supported under Windows, which means that

17046

+pure Python modules and extension modules are installed into the same location.

17047

+Files are installed as follows:

17048

17049

-+------------------------------+---------------------------+-----------------------------+

17050

-| Type of file | Installation Directory | Override option |

17051

-+==============================+===========================+=============================+

17052

-| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` |

17053

-+------------------------------+---------------------------+-----------------------------+

17054

-| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` |

17055

-+------------------------------+---------------------------+-----------------------------+

17056

-| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` |

17057

-+------------------------------+---------------------------+-----------------------------+

17058

-| data | :file:`{prefix}\\Data` | :option:`--install-data` |

17059

-+------------------------------+---------------------------+-----------------------------+

17060

+=============== ==========================================================

17061

+Type of file Installation directory

17062

+=============== ==========================================================

17063

+modules :file:`{prefix}\\Lib\\site-packages`

17064

+scripts :file:`{prefix}\\Scripts`

17065

+data :file:`{prefix}`

17066

+C headers :file:`{prefix}\\Include\\{distname}`

17067

+=============== ==========================================================

17068

17069

17070

.. _inst-custom-install:

17071

@@ -460,13 +522,29 @@

17072

or you might want to completely redefine the installation scheme. In either

17073

case, you're creating a *custom installation scheme*.

17074

17075

-You probably noticed the column of "override options" in the tables describing

17076

-the alternate installation schemes above. Those options are how you define a

17077

-custom installation scheme. These override options can be relative, absolute,

17078

+To create a custom installation scheme, you start with one of the alternate

17079

+schemes and override some of the installation directories used for the various

17080

+types of files, using these options:

17081

+

17082

+====================== =======================

17083

+Type of file Override option

17084

+====================== =======================

17085

+Python modules ``--install-purelib``

17086

+extension modules ``--install-platlib``

17087

+all modules ``--install-lib``

17088

+scripts ``--install-scripts``

17089

+data ``--install-data``

17090

+C headers ``--install-headers``

17091

+====================== =======================

17092

+

17093

+These override options can be relative, absolute,

17094

or explicitly defined in terms of one of the installation base directories.

17095

(There are two installation base directories, and they are normally the same---

17096

they only differ when you use the Unix "prefix scheme" and supply different

17097

-:option:`--prefix` and :option:`--exec-prefix` options.)

17098

+``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` will

17099

+override values computed or given for ``--install-purelib`` and

17100

+``--install-platlib``, and is recommended for schemes that don't make a

17101

+difference between Python and extension modules.)

17102

17103

For example, say you're installing a module distribution to your home directory

17104

under Unix---but you want scripts to go in :file:`~/scripts` rather than

17105

@@ -493,15 +571,16 @@

17106

a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}`

17107

itself. This is almost as easy as customizing the script installation directory

17108

---you just have to remember that there are two types of modules to worry about,

17109

-pure modules and non-pure modules (i.e., modules from a non-pure distribution).

17110

-For example::

17111

+Python and extension modules, which can conveniently be both controlled by one

17112

+option::

17113

17114

- python setup.py install --install-purelib=Site --install-platlib=Site

17115

+ python setup.py install --install-lib=Site

17116

17117

-The specified installation directories are relative to :file:`{prefix}`. Of

17118

-course, you also have to ensure that these directories are in Python's module

17119

-search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See

17120

-section :ref:`inst-search-path` to find out how to modify Python's search path.

17121

+The specified installation directory is relative to :file:`{prefix}`. Of

17122

+course, you also have to ensure that this directory is in Python's module

17123

+search path, such as by putting a :file:`.pth` file in a site directory (see

17124

+:mod:`site`). See section :ref:`inst-search-path` to find out how to modify

17125

+Python's search path.

17126

17127

If you want to define an entire installation scheme, you just have to supply all

17128

of the installation directory options. The recommended way to do this is to

17129

@@ -553,8 +632,8 @@

17130

17131

python setup.py install --install-base=/tmp

17132

17133

-would install pure modules to :file:`{/tmp/python/lib}` in the first case, and

17134

-to :file:`{/tmp/lib}` in the second case. (For the second case, you probably

17135

+would install pure modules to :file:`/tmp/python/lib` in the first case, and

17136

+to :file:`/tmp/lib` in the second case. (For the second case, you probably

17137

want to supply an installation base of :file:`/tmp/python`.)

17138

17139

You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample

17140

@@ -571,7 +650,7 @@

17141

needed on those platforms?

17142

17143

17144

-.. XXX I'm not sure where this section should go.

17145

+.. XXX Move this to Doc/using

17146

17147

.. _inst-search-path:

17148

17149

diff -r 8527427914a2 Doc/library/2to3.rst

17150

--- a/Doc/library/2to3.rst

17151

+++ b/Doc/library/2to3.rst

17152

@@ -94,6 +94,38 @@

17153

:option:`-p` to run fixers on code that already has had its print statements

17154

converted.

17155

17156

+The :option:`-o` or :option:`--output-dir` option allows specification of an

17157

+alternate directory for processed output files to be written to. The

17158

+:option:`-n` flag is required when using this as backup files do not make sense

17159

+when not overwriting the input files.

17160

+

17161

+.. versionadded:: 2.7.3

17162

+ The :option:`-o` option was added.

17163

+

17164

+The :option:`-W` or :option:`--write-unchanged-files` flag tells 2to3 to always

17165

+write output files even if no changes were required to the file. This is most

17166

+useful with :option:`-o` so that an entire Python source tree is copied with

17167

+translation from one directory to another.

17168

+This option implies the :option:`-w` flag as it would not make sense otherwise.

17169

+

17170

+.. versionadded:: 2.7.3

17171

+ The :option:`-W` flag was added.

17172

+

17173

+The :option:`--add-suffix` option specifies a string to append to all output

17174

+filenames. The :option:`-n` flag is required when specifying this as backups

17175

+are not necessary when writing to different filenames. Example::

17176

+

17177

+ $ 2to3 -n -W --add-suffix=3 example.py

17178

+

17179

+Will cause a converted file named ``example.py3`` to be written.

17180

+

17181

+.. versionadded:: 2.7.3

17182

+ The :option:`--add-suffix` option was added.

17183

+

17184

+To translate an entire project from one directory tree to another use::

17185

+

17186

+ $ 2to3 --output-dir=python3-version/mycode -W -n python2-version/mycode

17187

+

17188

17189

.. _2to3-fixers:

17190

17191

@@ -123,7 +155,9 @@

17192

.. 2to3fixer:: callable

17193

17194

Converts ``callable(x)`` to ``isinstance(x, collections.Callable)``, adding

17195

- an import to :mod:`collections` if needed.

17196

+ an import to :mod:`collections` if needed. Note ``callable(x)`` has returned

17197

+ in Python 3.2, so if you do not intend to support Python 3.1, you can disable

17198

+ this fixer.

17199

17200

.. 2to3fixer:: dict

17201

17202

@@ -230,7 +264,7 @@

17203

17204

.. 2to3fixer:: long

17205

17206

- Strips the ``L`` prefix on long literals and renames :class:`long` to

17207

+ Strips the ``L`` suffix on long literals and renames :class:`long` to

17208

:class:`int`.

17209

17210

.. 2to3fixer:: map

17211

diff -r 8527427914a2 Doc/library/__builtin__.rst

17212

--- a/Doc/library/__builtin__.rst

17213

+++ b/Doc/library/__builtin__.rst

17214

@@ -8,7 +8,9 @@

17215

17216

This module provides direct access to all 'built-in' identifiers of Python; for

17217

example, ``__builtin__.open`` is the full name for the built-in function

17218

-:func:`open`.

17219

+:func:`open`. See :ref:`built-in-funcs` and :ref:`built-in-consts` for

17220

+documentation.

17221

+

17222

17223

This module is not normally accessed explicitly by most applications, but can be

17224

useful in modules that provide objects with the same name as a built-in value,

17225

diff -r 8527427914a2 Doc/library/__future__.rst

17226

--- a/Doc/library/__future__.rst

17227

+++ b/Doc/library/__future__.rst

17228

@@ -4,6 +4,9 @@

17229

.. module:: __future__

17230

:synopsis: Future statement definitions

17231

17232

+**Source code:** :source:`Lib/__future__.py`

17233

+

17234

+--------------

17235

17236

:mod:`__future__` is a real module, and serves three purposes:

17237

17238

diff -r 8527427914a2 Doc/library/abc.rst

17239

--- a/Doc/library/abc.rst

17240

+++ b/Doc/library/abc.rst

17241

@@ -9,8 +9,12 @@

17242

17243

.. versionadded:: 2.6

17244

17245

-This module provides the infrastructure for defining an :term:`abstract base

17246

-class` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this

17247

+**Source code:** :source:`Lib/abc.py`

17248

+

17249

+--------------

17250

+

17251

+This module provides the infrastructure for defining :term:`abstract base

17252

+classes <abstract base class>` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this

17253

was added to Python. (See also :pep:`3141` and the :mod:`numbers` module

17254

regarding a type hierarchy for numbers based on ABCs.)

17255

17256

diff -r 8527427914a2 Doc/library/aifc.rst

17257

--- a/Doc/library/aifc.rst

17258

+++ b/Doc/library/aifc.rst

17259

@@ -10,6 +10,10 @@

17260

single: AIFF

17261

single: AIFF-C

17262

17263

+**Source code:** :source:`Lib/aifc.py`

17264

+

17265

+--------------

17266

+

17267

This module provides support for reading and writing AIFF and AIFF-C files.

17268

AIFF is Audio Interchange File Format, a format for storing digital audio

17269

samples in a file. AIFF-C is a newer version of the format that includes the

17270

diff -r 8527427914a2 Doc/library/al.rst

17271

--- a/Doc/library/al.rst

17272

+++ b/Doc/library/al.rst

17273

@@ -53,7 +53,7 @@

17274

.. function:: queryparams(device)

17275

17276

The device argument is an integer. The return value is a list of integers

17277

- containing the data returned by :cfunc:`ALqueryparams`.

17278

+ containing the data returned by :c:func:`ALqueryparams`.

17279

17280

17281

.. function:: getparams(device, list)

17282

diff -r 8527427914a2 Doc/library/argparse.rst

17283

--- a/Doc/library/argparse.rst

17284

+++ b/Doc/library/argparse.rst

17285

@@ -2,11 +2,15 @@

17286

===============================================================================

17287

17288

.. module:: argparse

17289

- :synopsis: Command-line option and argument-parsing library.

17290

+ :synopsis: Command-line option and argument parsing library.

17291

.. moduleauthor:: Steven Bethard <steven.bethard@gmail.com>

17292

-.. versionadded:: 2.7

17293

.. sectionauthor:: Steven Bethard <steven.bethard@gmail.com>

17294

17295

+.. versionadded:: 2.7

17296

+

17297

+**Source code:** :source:`Lib/argparse.py`

17298

+

17299

+--------------

17300

17301

The :mod:`argparse` module makes it easy to write user-friendly command-line

17302

interfaces. The program defines what arguments it requires, and :mod:`argparse`

17303

@@ -103,10 +107,10 @@

17304

Parsing arguments

17305

^^^^^^^^^^^^^^^^^

17306

17307

-:class:`ArgumentParser` parses args through the

17308

+:class:`ArgumentParser` parses arguments through the

17309

:meth:`~ArgumentParser.parse_args` method. This will inspect the command line,

17310

-convert each arg to the appropriate type and then invoke the appropriate action.

17311

-In most cases, this means a simple namespace object will be built up from

17312

+convert each argument to the appropriate type and then invoke the appropriate action.

17313

+In most cases, this means a simple :class:`Namespace` object will be built up from

17314

attributes parsed out of the command line::

17315

17316

>>> parser.parse_args(['--sum', '7', '-1', '42'])

17317

@@ -114,7 +118,7 @@

17318

17319

In a script, :meth:`~ArgumentParser.parse_args` will typically be called with no

17320

arguments, and the :class:`ArgumentParser` will automatically determine the

17321

-command-line args from :data:`sys.argv`.

17322

+command-line arguments from :data:`sys.argv`.

17323

17324

17325

ArgumentParser objects

17326

@@ -149,7 +153,7 @@

17327

conflicting optionals.

17328

17329

* prog_ - The name of the program (default:

17330

- :data:`sys.argv[0]`)

17331

+ ``sys.argv[0]``)

17332

17333

* usage_ - The string describing the program usage (default: generated)

17334

17335

@@ -238,7 +242,7 @@

17336

--foo FOO foo help

17337

17338

The help option is typically ``-h/--help``. The exception to this is

17339

-if the ``prefix_chars=`` is specified and does not include ``'-'``, in

17340

+if the ``prefix_chars=`` is specified and does not include ``-``, in

17341

which case ``-h`` and ``--help`` are not valid options. In

17342

this case, the first character in ``prefix_chars`` is used to prefix

17343

the help options::

17344

@@ -254,7 +258,7 @@

17345

prefix_chars

17346

^^^^^^^^^^^^

17347

17348

-Most command-line options will use ``'-'`` as the prefix, e.g. ``-f/--foo``.

17349

+Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.

17350

Parsers that need to support different or additional prefix

17351

characters, e.g. for options

17352

like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument

17353

@@ -267,7 +271,7 @@

17354

Namespace(bar='Y', f='X')

17355

17356

The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of

17357

-characters that does not include ``'-'`` will cause ``-f/--foo`` options to be

17358

+characters that does not include ``-`` will cause ``-f/--foo`` options to be

17359

disallowed.

17360

17361

17362

@@ -389,7 +393,7 @@

17363

likewise for this epilog whose whitespace will be cleaned up and whose words

17364

will be wrapped across a couple lines

17365

17366

-Passing :class:`~argparse.RawDescriptionHelpFormatter` as ``formatter_class=``

17367

+Passing :class:`RawDescriptionHelpFormatter` as ``formatter_class=``

17368

indicates that description_ and epilog_ are already correctly formatted and

17369

should not be line-wrapped::

17370

17371

@@ -415,7 +419,7 @@

17372

optional arguments:

17373

-h, --help show this help message and exit

17374

17375

-:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text

17376

+:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,

17377

including argument descriptions.

17378

17379

The other formatter class available, :class:`ArgumentDefaultsHelpFormatter`,

17380

@@ -642,11 +646,11 @@

17381

action

17382

^^^^^^

17383

17384

-:class:`ArgumentParser` objects associate command-line args with actions. These

17385

-actions can do just about anything with the command-line args associated with

17386

+:class:`ArgumentParser` objects associate command-line arguments with actions. These

17387

+actions can do just about anything with the command-line arguments associated with

17388

them, though most actions simply add an attribute to the object returned by

17389

:meth:`~ArgumentParser.parse_args`. The ``action`` keyword argument specifies

17390

-how the command-line args should be handled. The supported actions are:

17391

+how the command-line arguments should be handled. The supported actions are:

17392

17393

* ``'store'`` - This just stores the argument's value. This is the default

17394

action. For example::

17395

@@ -666,15 +670,17 @@

17396

>>> parser.parse_args('--foo'.split())

17397

Namespace(foo=42)

17398

17399

-* ``'store_true'`` and ``'store_false'`` - These store the values ``True`` and

17400

- ``False`` respectively. These are special cases of ``'store_const'``. For

17401

- example::

17402

+* ``'store_true'`` and ``'store_false'`` - These are special cases of

17403

+ ``'store_const'`` using for storing the values ``True`` and ``False``

17404

+ respectively. In addition, they create default values of *False* and *True*

17405

+ respectively. For example::

17406

17407

>>> parser = argparse.ArgumentParser()

17408

>>> parser.add_argument('--foo', action='store_true')

17409

>>> parser.add_argument('--bar', action='store_false')

17410

+ >>> parser.add_argument('--baz', action='store_false')

17411

>>> parser.parse_args('--foo --bar'.split())

17412

- Namespace(bar=False, foo=True)

17413

+ Namespace(bar=False, baz=True, foo=True)

17414

17415

* ``'append'`` - This stores a list, and appends each argument value to the

17416

list. This is useful to allow an option to be specified multiple times.

17417

@@ -697,6 +703,19 @@

17418

>>> parser.parse_args('--str --int'.split())

17419

Namespace(types=[<type 'str'>, <type 'int'>])

17420

17421

+* ``'count'`` - This counts the number of times a keyword argument occurs. For

17422

+ example, this is useful for increasing verbosity levels::

17423

+

17424

+ >>> parser = argparse.ArgumentParser()

17425

+ >>> parser.add_argument('--verbose', '-v', action='count')

17426

+ >>> parser.parse_args('-vvv'.split())

17427

+ Namespace(verbose=3)

17428

+

17429

+* ``'help'`` - This prints a complete help message for all the options in the

17430

+ current parser and then exits. By default a help action is automatically

17431

+ added to the parser. See :class:`ArgumentParser` for details of how the

17432

+ output is created.

17433

+

17434

* ``'version'`` - This expects a ``version=`` keyword argument in the

17435

:meth:`~ArgumentParser.add_argument` call, and prints version information

17436

and exits when invoked.

17437

@@ -714,12 +733,12 @@

17438

17439

* ``parser`` - The ArgumentParser object which contains this action.

17440

17441

-* ``namespace`` - The namespace object that will be returned by

17442

+* ``namespace`` - The :class:`Namespace` object that will be returned by

17443

:meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this

17444

object.

17445

17446

-* ``values`` - The associated command-line args, with any type-conversions

17447

- applied. (Type-conversions are specified with the type_ keyword argument to

17448

+* ``values`` - The associated command-line arguments, with any type conversions

17449

+ applied. (Type conversions are specified with the type_ keyword argument to

17450

:meth:`~ArgumentParser.add_argument`.

17451

17452

* ``option_string`` - The option string that was used to invoke this action.

17453

@@ -751,7 +770,7 @@

17454

different number of command-line arguments with a single action. The supported

17455

values are:

17456

17457

-* N (an integer). N args from the command line will be gathered together into a

17458

+* ``N`` (an integer). ``N`` arguments from the command line will be gathered together into a

17459

list. For example::

17460

17461

>>> parser = argparse.ArgumentParser()

17462

@@ -763,11 +782,11 @@

17463

Note that ``nargs=1`` produces a list of one item. This is different from

17464

the default, in which the item is produced by itself.

17465

17466

-* ``'?'``. One arg will be consumed from the command line if possible, and

17467

- produced as a single item. If no command-line arg is present, the value from

17468

+* ``'?'``. One argument will be consumed from the command line if possible, and

17469

+ produced as a single item. If no command-line argument is present, the value from

17470

default_ will be produced. Note that for optional arguments, there is an

17471

additional case - the option string is present but not followed by a

17472

- command-line arg. In this case the value from const_ will be produced. Some

17473

+ command-line argument. In this case the value from const_ will be produced. Some

17474

examples to illustrate this::

17475

17476

>>> parser = argparse.ArgumentParser()

17477

@@ -795,7 +814,7 @@

17478

Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>,

17479

outfile=<open file '<stdout>', mode 'w' at 0x...>)

17480

17481

-* ``'*'``. All command-line args present are gathered into a list. Note that

17482

+* ``'*'``. All command-line arguments present are gathered into a list. Note that

17483

it generally doesn't make much sense to have more than one positional argument

17484

with ``nargs='*'``, but multiple optional arguments with ``nargs='*'`` is

17485

possible. For example::

17486

@@ -809,7 +828,7 @@

17487

17488

* ``'+'``. Just like ``'*'``, all command-line args present are gathered into a

17489

list. Additionally, an error message will be generated if there wasn't at

17490

- least one command-line arg present. For example::

17491

+ least one command-line argument present. For example::

17492

17493

>>> parser = argparse.ArgumentParser(prog='PROG')

17494

>>> parser.add_argument('foo', nargs='+')

17495

@@ -819,8 +838,19 @@

17496

usage: PROG [-h] foo [foo ...]

17497

PROG: error: too few arguments

17498

17499

-If the ``nargs`` keyword argument is not provided, the number of args consumed

17500

-is determined by the action_. Generally this means a single command-line arg

17501

+* ``argparse.REMAINDER``. All the remaining command-line arguments are gathered

17502

+ into a list. This is commonly useful for command line utilities that dispatch

17503

+ to other command line utilities.

17504

+

17505

+ >>> parser = argparse.ArgumentParser(prog='PROG')

17506

+ >>> parser.add_argument('--foo')

17507

+ >>> parser.add_argument('command')

17508

+ >>> parser.add_argument('args', nargs=argparse.REMAINDER)

17509

+ >>> print parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())

17510

+ Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')

17511

+

17512

+If the ``nargs`` keyword argument is not provided, the number of arguments consumed

17513

+is determined by the action_. Generally this means a single command-line argument

17514

will be consumed and a single item (not a list) will be produced.

17515

17516

17517

@@ -837,9 +867,9 @@

17518

17519

* When :meth:`~ArgumentParser.add_argument` is called with option strings

17520

(like ``-f`` or ``--foo``) and ``nargs='?'``. This creates an optional

17521

- argument that can be followed by zero or one command-line args.

17522

+ argument that can be followed by zero or one command-line arguments.

17523

When parsing the command line, if the option string is encountered with no

17524

- command-line arg following it, the value of ``const`` will be assumed instead.

17525

+ command-line argument following it, the value of ``const`` will be assumed instead.

17526

See the nargs_ description for examples.

17527

17528

The ``const`` keyword argument defaults to ``None``.

17529

@@ -851,7 +881,7 @@

17530

All optional arguments and some positional arguments may be omitted at the

17531

command line. The ``default`` keyword argument of

17532

:meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``,

17533

-specifies what value should be used if the command-line arg is not present.

17534

+specifies what value should be used if the command-line argument is not present.

17535

For optional arguments, the ``default`` value is used when the option string

17536

was not present at the command line::

17537

17538

@@ -862,8 +892,8 @@

17539

>>> parser.parse_args(''.split())

17540

Namespace(foo=42)

17541

17542

-For positional arguments with nargs_ ``='?'`` or ``'*'``, the ``default`` value

17543

-is used when no command-line arg was present::

17544

+For positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value

17545

+is used when no command-line argument was present::

17546

17547

>>> parser = argparse.ArgumentParser()

17548

>>> parser.add_argument('foo', nargs='?', default=42)

17549

@@ -887,12 +917,12 @@

17550

type

17551

^^^^

17552

17553

-By default, ArgumentParser objects read command-line args in as simple strings.

17554

-However, quite often the command-line string should instead be interpreted as

17555

-another type, like a :class:`float`, :class:`int` or :class:`file`. The

17556

+By default, :class:`ArgumentParser` objects read command-line arguments in as simple

17557

+strings. However, quite often the command-line string should instead be

17558

+interpreted as another type, like a :class:`float` or :class:`int`. The

17559

``type`` keyword argument of :meth:`~ArgumentParser.add_argument` allows any

17560

-necessary type-checking and type-conversions to be performed. Many common

17561

-built-in types can be used directly as the value of the ``type`` argument::

17562

+necessary type-checking and type conversions to be performed. Common built-in

17563

+types and functions can be used directly as the value of the ``type`` argument::

17564

17565

>>> parser = argparse.ArgumentParser()

17566

>>> parser.add_argument('foo', type=int)

17567

@@ -911,7 +941,7 @@

17568

Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>)

17569

17570

``type=`` can take any callable that takes a single string argument and returns

17571

-the type-converted value::

17572

+the converted value::

17573

17574

>>> def perfect_square(string):

17575

... value = int(string)

17576

@@ -946,11 +976,11 @@

17577

choices

17578

^^^^^^^

17579

17580

-Some command-line args should be selected from a restricted set of values.

17581

+Some command-line arguments should be selected from a restricted set of values.

17582

These can be handled by passing a container object as the ``choices`` keyword

17583

argument to :meth:`~ArgumentParser.add_argument`. When the command line is

17584

-parsed, arg values will be checked, and an error message will be displayed if

17585

-the arg was not one of the acceptable values::

17586

+parsed, argument values will be checked, and an error message will be displayed if

17587

+the argument was not one of the acceptable values::

17588

17589

>>> parser = argparse.ArgumentParser(prog='PROG')

17590

>>> parser.add_argument('foo', choices='abc')

17591

@@ -1043,6 +1073,17 @@

17592

optional arguments:

17593

-h, --help show this help message and exit

17594

17595

+:mod:`argparse` supports silencing the help entry for certain options, by

17596

+setting the ``help`` value to ``argparse.SUPPRESS``::

17597

+

17598

+ >>> parser = argparse.ArgumentParser(prog='frobble')

17599

+ >>> parser.add_argument('--foo', help=argparse.SUPPRESS)

17600

+ >>> parser.print_help()

17601

+ usage: frobble [-h]

17602

+

17603

+ optional arguments:

17604

+ -h, --help show this help message and exit

17605

+

17606

17607

metavar

17608

^^^^^^^

17609

@@ -1052,8 +1093,8 @@

17610

value as the "name" of each object. By default, for positional argument

17611

actions, the dest_ value is used directly, and for optional argument actions,

17612

the dest_ value is uppercased. So, a single positional argument with

17613

-``dest='bar'`` will that argument will be referred to as ``bar``. A single

17614

-optional argument ``--foo`` that should be followed by a single command-line arg

17615

+``dest='bar'`` will be referred to as ``bar``. A single

17616

+optional argument ``--foo`` that should be followed by a single command-line argument

17617

will be referred to as ``FOO``. An example::

17618

17619

>>> parser = argparse.ArgumentParser()

17620

@@ -1125,10 +1166,10 @@

17621

17622

For optional argument actions, the value of ``dest`` is normally inferred from

17623

the option strings. :class:`ArgumentParser` generates the value of ``dest`` by

17624

-taking the first long option string and stripping away the initial ``'--'``

17625

+taking the first long option string and stripping away the initial ``--``

17626

string. If no long option strings were supplied, ``dest`` will be derived from

17627

-the first short option string by stripping the initial ``'-'`` character. Any

17628

-internal ``'-'`` characters will be converted to ``'_'`` characters to make sure

17629

+the first short option string by stripping the initial ``-`` character. Any

17630

+internal ``-`` characters will be converted to ``_`` characters to make sure

17631

the string is a valid attribute name. The examples below illustrate this

17632

behavior::

17633

17634

@@ -1160,7 +1201,7 @@

17635

created and how they are assigned. See the documentation for

17636

:meth:`add_argument` for details.

17637

17638

- By default, the arg strings are taken from :data:`sys.argv`, and a new empty

17639

+ By default, the argument strings are taken from :data:`sys.argv`, and a new empty

17640

:class:`Namespace` object is created for the attributes.

17641

17642

17643

@@ -1231,15 +1272,15 @@

17644

PROG: error: extra arguments found: badger

17645

17646

17647

-Arguments containing ``"-"``

17648

-^^^^^^^^^^^^^^^^^^^^^^^^^^^^

17649

+Arguments containing ``-``

17650

+^^^^^^^^^^^^^^^^^^^^^^^^^^

17651

17652

The :meth:`~ArgumentParser.parse_args` method attempts to give errors whenever

17653

the user has clearly made a mistake, but some situations are inherently

17654

-ambiguous. For example, the command-line arg ``'-1'`` could either be an

17655

+ambiguous. For example, the command-line argument ``-1`` could either be an

17656

attempt to specify an option or an attempt to provide a positional argument.

17657

The :meth:`~ArgumentParser.parse_args` method is cautious here: positional

17658

-arguments may only begin with ``'-'`` if they look like negative numbers and

17659

+arguments may only begin with ``-`` if they look like negative numbers and

17660

there are no options in the parser that look like negative numbers::

17661

17662

>>> parser = argparse.ArgumentParser(prog='PROG')

17663

@@ -1272,7 +1313,7 @@

17664

usage: PROG [-h] [-1 ONE] [foo]

17665

PROG: error: argument -1: expected one argument

17666

17667

-If you have positional arguments that must begin with ``'-'`` and don't look

17668

+If you have positional arguments that must begin with ``-`` and don't look

17669

like negative numbers, you can insert the pseudo-argument ``'--'`` which tells

17670

:meth:`~ArgumentParser.parse_args` that everything after that is a positional

17671

argument::

17672

@@ -1304,7 +1345,7 @@

17673

Beyond ``sys.argv``

17674

^^^^^^^^^^^^^^^^^^^

17675

17676

-Sometimes it may be useful to have an ArgumentParser parse args other than those

17677

+Sometimes it may be useful to have an ArgumentParser parse arguments other than those

17678

of :data:`sys.argv`. This can be accomplished by passing a list of strings to

17679

:meth:`~ArgumentParser.parse_args`. This is useful for testing at the

17680

interactive prompt::

17681

@@ -1325,11 +1366,14 @@

17682

The Namespace object

17683

^^^^^^^^^^^^^^^^^^^^

17684

17685

-By default, :meth:`~ArgumentParser.parse_args` will return a new object of type

17686

-:class:`Namespace` where the necessary attributes have been set. This class is

17687

-deliberately simple, just an :class:`object` subclass with a readable string

17688

-representation. If you prefer to have dict-like view of the attributes, you

17689

-can use the standard Python idiom via :func:`vars`::

17690

+.. class:: Namespace

17691

+

17692

+ Simple class used by default by :meth:`~ArgumentParser.parse_args` to create

17693

+ an object holding attributes and return it.

17694

+

17695

+This class is deliberately simple, just an :class:`object` subclass with a

17696

+readable string representation. If you prefer to have dict-like view of the

17697

+attributes, you can use the standard Python idiom, :func:`vars`::

17698

17699

>>> parser = argparse.ArgumentParser()

17700

>>> parser.add_argument('--foo')

17701

@@ -1387,7 +1431,7 @@

17702

>>> parser_b = subparsers.add_parser('b', help='b help')

17703

>>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')

17704

>>>

17705

- >>> # parse some arg lists

17706

+ >>> # parse some argument lists

17707

>>> parser.parse_args(['a', '12'])

17708

Namespace(bar=12, foo=False)

17709

>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])

17710

@@ -1396,8 +1440,8 @@

17711

Note that the object returned by :meth:`parse_args` will only contain

17712

attributes for the main parser and the subparser that was selected by the

17713

command line (and not any other subparsers). So in the example above, when

17714

- the ``"a"`` command is specified, only the ``foo`` and ``bar`` attributes are

17715

- present, and when the ``"b"`` command is specified, only the ``foo`` and

17716

+ the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are

17717

+ present, and when the ``b`` command is specified, only the ``foo`` and

17718

``baz`` attributes are present.

17719

17720

Similarly, when a help message is requested from a subparser, only the help

17721

@@ -1519,7 +1563,7 @@

17722

17723

The :class:`FileType` factory creates objects that can be passed to the type

17724

argument of :meth:`ArgumentParser.add_argument`. Arguments that have

17725

- :class:`FileType` objects as their type will open command-line args as files

17726

+ :class:`FileType` objects as their type will open command-line arguments as files

17727

with the requested modes and buffer sizes:

17728

17729

>>> parser = argparse.ArgumentParser()

17730

@@ -1633,7 +1677,7 @@

17731

.. method:: ArgumentParser.set_defaults(**kwargs)

17732

17733

Most of the time, the attributes of the object returned by :meth:`parse_args`

17734

- will be fully determined by inspecting the command-line args and the argument

17735

+ will be fully determined by inspecting the command-line arguments and the argument

17736

actions. :meth:`set_defaults` allows some additional

17737

attributes that are determined without any inspection of the command line to

17738

be added::

17739

@@ -1757,7 +1801,7 @@

17740

.. method:: ArgumentParser.error(message)

17741

17742

This method prints a usage message including the *message* to the

17743

- standard output and terminates the program with a status code of 2.

17744

+ standard error and terminates the program with a status code of 2.

17745

17746

17747

.. _argparse-from-optparse:

17748

diff -r 8527427914a2 Doc/library/array.rst

17749

--- a/Doc/library/array.rst

17750

+++ b/Doc/library/array.rst

17751

@@ -107,7 +107,7 @@

17752

memory buffer in bytes can be computed as ``array.buffer_info()[1] *

17753

array.itemsize``. This is occasionally useful when working with low-level (and

17754

inherently unsafe) I/O interfaces that require memory addresses, such as certain

17755

- :cfunc:`ioctl` operations. The returned numbers are valid as long as the array

17756

+ :c:func:`ioctl` operations. The returned numbers are valid as long as the array

17757

exists and no length-changing operations are applied to it.

17758

17759

.. note::

17760

diff -r 8527427914a2 Doc/library/ast.rst

17761

--- a/Doc/library/ast.rst

17762

+++ b/Doc/library/ast.rst

17763

@@ -1,7 +1,5 @@

17764

-.. _ast:

17765

-

17766

-Abstract Syntax Trees

17767

-=====================

17768

+:mod:`ast` --- Abstract Syntax Trees

17769

+====================================

17770

17771

.. module:: ast

17772

:synopsis: Abstract Syntax Tree classes and manipulation.

17773

@@ -15,6 +13,9 @@

17774

.. versionadded:: 2.6

17775

The high-level ``ast`` module containing all helpers.

17776

17777

+**Source code:** :source:`Lib/ast.py`

17778

+

17779

+--------------

17780

17781

The :mod:`ast` module helps Python applications to process trees of the Python

17782

abstract syntax grammar. The abstract syntax itself might change with each

17783

@@ -28,11 +29,6 @@

17784

compiled into a Python code object using the built-in :func:`compile` function.

17785

17786

17787

-.. seealso::

17788

-

17789

- Latest version of the `ast module Python source code

17790

- <http://svn.python.org/view/python/branches/release27-maint/Lib/ast.py?view=markup>`_

17791

-

17792

Node classes

17793

------------

17794

17795

diff -r 8527427914a2 Doc/library/asynchat.rst

17796

--- a/Doc/library/asynchat.rst

17797

+++ b/Doc/library/asynchat.rst

17798

@@ -1,4 +1,3 @@

17799

-

17800

:mod:`asynchat` --- Asynchronous socket command/response handler

17801

================================================================

17802

17803

@@ -7,6 +6,9 @@

17804

.. moduleauthor:: Sam Rushing <rushing@nightmare.com>

17805

.. sectionauthor:: Steve Holden <sholden@holdenweb.com>

17806

17807

+**Source code:** :source:`Lib/asynchat.py`

17808

+

17809

+--------------

17810

17811

This module builds on the :mod:`asyncore` infrastructure, simplifying

17812

asynchronous clients and servers and making it easier to handle protocols

17813

@@ -32,7 +34,7 @@

17814

17815

Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of

17816

events that are generated by an analysis of socket conditions after a

17817

- :cfunc:`select` call. Once the polling loop has been started the

17818

+ :c:func:`select` call. Once the polling loop has been started the

17819

:class:`async_chat` object's methods are called by the event-processing

17820

framework with no action on the part of the programmer.

17821

17822

diff -r 8527427914a2 Doc/library/asyncore.rst

17823

--- a/Doc/library/asyncore.rst

17824

+++ b/Doc/library/asyncore.rst

17825

@@ -1,4 +1,3 @@

17826

-

17827

:mod:`asyncore` --- Asynchronous socket handler

17828

===============================================

17829

17830

@@ -10,6 +9,9 @@

17831

.. sectionauthor:: Steve Holden <sholden@holdenweb.com>

17832

.. heavily adapted from original documentation by Sam Rushing

17833

17834

+**Source code:** :source:`Lib/asyncore.py`

17835

+

17836

+--------------

17837

17838

This module provides the basic infrastructure for writing asynchronous socket

17839

service clients and servers.

17840

@@ -23,7 +25,7 @@

17841

are probably what you really need. Network servers are rarely processor

17842

bound, however.

17843

17844

-If your operating system supports the :cfunc:`select` system call in its I/O

17845

+If your operating system supports the :c:func:`select` system call in its I/O

17846

library (and nearly all do), then you can use it to juggle multiple

17847

communication channels at once; doing other work while your I/O is taking

17848

place in the "background." Although this strategy can seem strange and

17849

@@ -93,8 +95,8 @@

17850

17851

During asynchronous processing, each mapped channel's :meth:`readable` and

17852

:meth:`writable` methods are used to determine whether the channel's socket

17853

- should be added to the list of channels :cfunc:`select`\ ed or

17854

- :cfunc:`poll`\ ed for read and write events.

17855

+ should be added to the list of channels :c:func:`select`\ ed or

17856

+ :c:func:`poll`\ ed for read and write events.

17857

17858

Thus, the set of channel events is larger than the basic socket events. The

17859

full set of methods that can be overridden in your subclass follows:

17860

@@ -236,9 +238,9 @@

17861

.. class:: file_dispatcher()

17862

17863

A file_dispatcher takes a file descriptor or file object along with an

17864

- optional map argument and wraps it for use with the :cfunc:`poll` or

17865

- :cfunc:`loop` functions. If provided a file object or anything with a

17866

- :cfunc:`fileno` method, that method will be called and passed to the

17867

+ optional map argument and wraps it for use with the :c:func:`poll` or

17868

+ :c:func:`loop` functions. If provided a file object or anything with a

17869

+ :c:func:`fileno` method, that method will be called and passed to the

17870

:class:`file_wrapper` constructor. Availability: UNIX.

17871

17872

.. class:: file_wrapper()

17873

diff -r 8527427914a2 Doc/library/atexit.rst

17874

--- a/Doc/library/atexit.rst

17875

+++ b/Doc/library/atexit.rst

17876

@@ -1,4 +1,3 @@

17877

-

17878

:mod:`atexit` --- Exit handlers

17879

===============================

17880

17881

@@ -10,14 +9,15 @@

17882

17883

.. versionadded:: 2.0

17884

17885

+**Source code:** :source:`Lib/atexit.py`

17886

+

17887

+--------------

17888

+

17889

The :mod:`atexit` module defines a single function to register cleanup

17890

functions. Functions thus registered are automatically executed upon normal

17891

-interpreter termination.

17892

-

17893

-.. seealso::

17894

-

17895

- Latest version of the `atexit Python source code

17896

- <http://svn.python.org/view/python/branches/release27-maint/Lib/atexit.py?view=markup>`_

17897

+interpreter termination. The order in which the functions are called is not

17898

+defined; if you have cleanup operations that depend on each other, you should

17899

+wrap them in a function and register that one. This keeps :mod:`atexit` simple.

17900

17901

Note: the functions registered via this module are not called when the program

17902

is killed by a signal not handled by Python, when a Python fatal internal error

17903

@@ -26,7 +26,7 @@

17904

.. index:: single: exitfunc (in sys)

17905

17906

This is an alternate interface to the functionality provided by the

17907

-``sys.exitfunc`` variable.

17908

+:func:`sys.exitfunc` variable.

17909

17910

Note: This module is unlikely to work correctly when used with other code that

17911

sets ``sys.exitfunc``. In particular, other core Python modules are free to use

17912

@@ -40,7 +40,8 @@

17913

17914

Register *func* as a function to be executed at termination. Any optional

17915

arguments that are to be passed to *func* must be passed as arguments to

17916

- :func:`register`.

17917

+ :func:`register`. It is possible to register the same function and arguments

17918

+ more than once.

17919

17920

At normal program termination (for instance, if :func:`sys.exit` is called or

17921

the main module's execution completes), all functions registered are called in

17922

@@ -54,8 +55,8 @@

17923

be raised is re-raised.

17924

17925

.. versionchanged:: 2.6

17926

- This function now returns *func* which makes it possible to use it as a

17927

- decorator without binding the original name to ``None``.

17928

+ This function now returns *func*, which makes it possible to use it as a

17929

+ decorator.

17930

17931

17932

.. seealso::

17933

@@ -109,5 +110,4 @@

17934

def goodbye():

17935

print "You are now leaving the Python sector."

17936

17937

-This obviously only works with functions that don't take arguments.

17938

-

17939

+This only works with functions that can be called without arguments.

17940

diff -r 8527427914a2 Doc/library/basehttpserver.rst

17941

--- a/Doc/library/basehttpserver.rst

17942

+++ b/Doc/library/basehttpserver.rst

17943

@@ -18,6 +18,10 @@

17944

module: SimpleHTTPServer

17945

module: CGIHTTPServer

17946

17947

+**Source code:** :source:`Lib/BaseHTTPServer.py`

17948

+

17949

+--------------

17950

+

17951

This module defines two classes for implementing HTTP servers (Web servers).

17952

Usually, this module isn't used directly, but is used as a basis for building

17953

functioning Web servers. See the :mod:`SimpleHTTPServer` and

17954

diff -r 8527427914a2 Doc/library/bdb.rst

17955

--- a/Doc/library/bdb.rst

17956

+++ b/Doc/library/bdb.rst

17957

@@ -4,6 +4,10 @@

17958

.. module:: bdb

17959

:synopsis: Debugger framework.

17960

17961

+**Source code:** :source:`Lib/bdb.py`

17962

+

17963

+--------------

17964

+

17965

The :mod:`bdb` module handles basic debugger functions, like setting breakpoints

17966

or managing execution via the debugger.

17967

17968

diff -r 8527427914a2 Doc/library/bisect.rst

17969

--- a/Doc/library/bisect.rst

17970

+++ b/Doc/library/bisect.rst

17971

@@ -7,6 +7,12 @@

17972

.. sectionauthor:: Raymond Hettinger <python at rcn.com>

17973

.. example based on the PyModules FAQ entry by Aaron Watters <arw@pythonpros.com>

17974

17975

+.. versionadded:: 2.1

17976

+

17977

+**Source code:** :source:`Lib/bisect.py`

17978

+

17979

+--------------

17980

+

17981

This module provides support for maintaining a list in sorted order without

17982

having to sort the list after each insertion. For long lists of items with

17983

expensive comparison operations, this can be an improvement over the more common

17984

@@ -14,13 +20,6 @@

17985

algorithm to do its work. The source code may be most useful as a working

17986

example of the algorithm (the boundary conditions are already right!).

17987

17988

-.. versionadded:: 2.1

17989

-

17990

-.. seealso::

17991

-

17992

- Latest version of the `bisect module Python source code

17993

- <http://svn.python.org/view/python/branches/release27-maint/Lib/bisect.py?view=markup>`_

17994

-

17995

The following functions are provided:

17996

17997

17998

diff -r 8527427914a2 Doc/library/bsddb.rst

17999

--- a/Doc/library/bsddb.rst

18000

+++ b/Doc/library/bsddb.rst

18001

@@ -54,7 +54,7 @@

18002

optional *flag* identifies the mode used to open the file. It may be ``'r'``

18003

(read only), ``'w'`` (read-write) , ``'c'`` (read-write - create if necessary;

18004

the default) or ``'n'`` (read-write - truncate to zero length). The other

18005

- arguments are rarely used and are just passed to the low-level :cfunc:`dbopen`

18006

+ arguments are rarely used and are just passed to the low-level :c:func:`dbopen`

18007

function. Consult the Berkeley DB documentation for their use and

18008

interpretation.

18009

18010

diff -r 8527427914a2 Doc/library/bz2.rst

18011

--- a/Doc/library/bz2.rst

18012

+++ b/Doc/library/bz2.rst

18013

@@ -67,6 +67,18 @@

18014

Support for the :keyword:`with` statement was added.

18015

18016

18017

+ .. note::

18018

+

18019

+ This class does not support input files containing multiple streams (such

18020

+ as those produced by the :program:`pbzip2` tool). When reading such an

18021

+ input file, only the first stream will be accessible. If you require

18022

+ support for multi-stream files, consider using the third-party

18023

+ :mod:`bz2file` module (available from

18024

+ `PyPI <http://pypi.python.org/pypi/bz2file>`_). This module provides a

18025

+ backport of Python 3.3's :class:`BZ2File` class, which does support

18026

+ multi-stream files.

18027

+

18028

+

18029

.. method:: close()

18030

18031

Close the file. Sets data attribute :attr:`closed` to true. A closed file

18032

diff -r 8527427914a2 Doc/library/calendar.rst

18033

--- a/Doc/library/calendar.rst

18034

+++ b/Doc/library/calendar.rst

18035

@@ -1,4 +1,3 @@

18036

-

18037

:mod:`calendar` --- General calendar-related functions

18038

======================================================

18039

18040

@@ -7,6 +6,9 @@

18041

program.

18042

.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com>

18043

18044

+**Source code:** :source:`Lib/calendar.py`

18045

+

18046

+--------------

18047

18048

This module allows you to output calendars like the Unix :program:`cal` program,

18049

and provides additional useful functions related to the calendar. By default,

18050

@@ -22,10 +24,6 @@

18051

calendar in Dershowitz and Reingold's book "Calendrical Calculations", where

18052

it's the base calendar for all computations.

18053

18054

-.. seealso::

18055

-

18056

- Latest version of the `calendar module Python source code

18057

- <http://svn.python.org/view/python/branches/release27-maint/Lib/calendar.py?view=markup>`_

18058

18059

.. class:: Calendar([firstweekday])

18060

18061

diff -r 8527427914a2 Doc/library/carbon.rst

18062

--- a/Doc/library/carbon.rst

18063

+++ b/Doc/library/carbon.rst

18064

@@ -14,7 +14,7 @@

18065

in Python (input and output buffers, especially). All methods and functions

18066

have a :attr:`__doc__` string describing their arguments and return values, and

18067

for additional description you are referred to `Inside Macintosh

18068

-<http://developer.apple.com/documentation/macos8/mac8.html>`_ or similar works.

18069

+<http://developer.apple.com/legacy/mac/library/#documentation/macos8/mac8.html>`_ or similar works.

18070

18071

These modules all live in a package called :mod:`Carbon`. Despite that name they

18072

are not all part of the Carbon framework: CF is really in the CoreFoundation

18073

@@ -515,7 +515,7 @@

18074

18075

.. seealso::

18076

18077

- `Scrap Manager <http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-109.html>`_

18078

+ `Scrap Manager <http://developer.apple.com/legacy/mac/library/documentation/mac/MoreToolbox/MoreToolbox-109.html>`_

18079

Apple's documentation for the Scrap Manager gives a lot of useful information

18080

about using the Scrap Manager in applications.

18081

18082

diff -r 8527427914a2 Doc/library/cgi.rst

18083

--- a/Doc/library/cgi.rst

18084

+++ b/Doc/library/cgi.rst

18085

@@ -13,6 +13,10 @@

18086

single: URL

18087

single: Common Gateway Interface

18088

18089

+**Source code:** :source:`Lib/cgi.py`

18090

+

18091

+--------------

18092

+

18093

Support module for Common Gateway Interface (CGI) scripts.

18094

18095

This module defines a number of utilities for use by CGI scripts written in

18096

diff -r 8527427914a2 Doc/library/cmd.rst

18097

--- a/Doc/library/cmd.rst

18098

+++ b/Doc/library/cmd.rst

18099

@@ -1,4 +1,3 @@

18100

-

18101

:mod:`cmd` --- Support for line-oriented command interpreters

18102

=============================================================

18103

18104

@@ -6,17 +5,15 @@

18105

:synopsis: Build line-oriented command interpreters.

18106

.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>

18107

18108

+**Source code:** :source:`Lib/cmd.py`

18109

+

18110

+--------------

18111

18112

The :class:`Cmd` class provides a simple framework for writing line-oriented

18113

command interpreters. These are often useful for test harnesses, administrative

18114

tools, and prototypes that will later be wrapped in a more sophisticated

18115

interface.

18116

18117

-.. seealso::

18118

-

18119

- Latest version of the `cmd module Python source code

18120

- <http://svn.python.org/view/python/branches/release27-maint/Lib/cmd.py?view=markup>`_

18121

-

18122

.. class:: Cmd([completekey[, stdin[, stdout]]])

18123

18124

A :class:`Cmd` instance or subclass instance is a line-oriented interpreter

18125

@@ -56,7 +53,7 @@

18126

the line as argument.

18127

18128

The optional argument is a banner or intro string to be issued before the first

18129

- prompt (this overrides the :attr:`intro` class member).

18130

+ prompt (this overrides the :attr:`intro` class attribute).

18131

18132

If the :mod:`readline` module is loaded, input will automatically inherit

18133

:program:`bash`\ -like history-list editing (e.g. :kbd:`Control-P` scrolls back

18134

diff -r 8527427914a2 Doc/library/codecs.rst

18135

--- a/Doc/library/codecs.rst

18136

+++ b/Doc/library/codecs.rst

18137

@@ -759,9 +759,9 @@

18138

---------------------

18139

18140

Unicode strings are stored internally as sequences of codepoints (to be precise

18141

-as :ctype:`Py_UNICODE` arrays). Depending on the way Python is compiled (either

18142

+as :c:type:`Py_UNICODE` arrays). Depending on the way Python is compiled (either

18143

via ``--enable-unicode=ucs2`` or ``--enable-unicode=ucs4``, with the

18144

-former being the default) :ctype:`Py_UNICODE` is either a 16-bit or 32-bit data

18145

+former being the default) :c:type:`Py_UNICODE` is either a 16-bit or 32-bit data

18146

type. Once a Unicode object is used outside of CPU and memory, CPU endianness

18147

and how these arrays are stored as bytes become an issue. Transforming a

18148

unicode object into a sequence of bytes is called encoding and recreating the

18149

@@ -782,27 +782,28 @@

18150

Windows). There's a string constant with 256 characters that shows you which

18151

character is mapped to which byte value.

18152

18153

-All of these encodings can only encode 256 of the 65536 (or 1114111) codepoints

18154

+All of these encodings can only encode 256 of the 1114112 codepoints

18155

defined in unicode. A simple and straightforward way that can store each Unicode

18156

-code point, is to store each codepoint as two consecutive bytes. There are two

18157

-possibilities: Store the bytes in big endian or in little endian order. These

18158

-two encodings are called UTF-16-BE and UTF-16-LE respectively. Their

18159

-disadvantage is that if e.g. you use UTF-16-BE on a little endian machine you

18160

-will always have to swap bytes on encoding and decoding. UTF-16 avoids this

18161

-problem: Bytes will always be in natural endianness. When these bytes are read

18162

+code point, is to store each codepoint as four consecutive bytes. There are two

18163

+possibilities: store the bytes in big endian or in little endian order. These

18164

+two encodings are called ``UTF-32-BE`` and ``UTF-32-LE`` respectively. Their

18165

+disadvantage is that if e.g. you use ``UTF-32-BE`` on a little endian machine you

18166

+will always have to swap bytes on encoding and decoding. ``UTF-32`` avoids this

18167

+problem: bytes will always be in natural endianness. When these bytes are read

18168

by a CPU with a different endianness, then bytes have to be swapped though. To

18169

-be able to detect the endianness of a UTF-16 byte sequence, there's the so

18170

-called BOM (the "Byte Order Mark"). This is the Unicode character ``U+FEFF``.

18171

-This character will be prepended to every UTF-16 byte sequence. The byte swapped

18172

-version of this character (``0xFFFE``) is an illegal character that may not

18173

-appear in a Unicode text. So when the first character in an UTF-16 byte sequence

18174

+be able to detect the endianness of a ``UTF-16`` or ``UTF-32`` byte sequence,

18175

+there's the so called BOM ("Byte Order Mark"). This is the Unicode character

18176

+``U+FEFF``. This character can be prepended to every ``UTF-16`` or ``UTF-32``

18177

+byte sequence. The byte swapped version of this character (``0xFFFE``) is an

18178

+illegal character that may not appear in a Unicode text. So when the

18179

+first character in an ``UTF-16`` or ``UTF-32`` byte sequence

18180

appears to be a ``U+FFFE`` the bytes have to be swapped on decoding.

18181

-Unfortunately upto Unicode 4.0 the character ``U+FEFF`` had a second purpose as

18182

-a ``ZERO WIDTH NO-BREAK SPACE``: A character that has no width and doesn't allow

18183

+Unfortunately the character ``U+FEFF`` had a second purpose as

18184

+a ``ZERO WIDTH NO-BREAK SPACE``: a character that has no width and doesn't allow

18185

a word to be split. It can e.g. be used to give hints to a ligature algorithm.

18186

With Unicode 4.0 using ``U+FEFF`` as a ``ZERO WIDTH NO-BREAK SPACE`` has been

18187

deprecated (with ``U+2060`` (``WORD JOINER``) assuming this role). Nevertheless

18188

-Unicode software still must be able to handle ``U+FEFF`` in both roles: As a BOM

18189

+Unicode software still must be able to handle ``U+FEFF`` in both roles: as a BOM

18190

it's a device to determine the storage layout of the encoded bytes, and vanishes

18191

once the byte sequence has been decoded into a Unicode string; as a ``ZERO WIDTH

18192

NO-BREAK SPACE`` it's a normal character that will be decoded like any other.

18193

@@ -810,8 +811,8 @@

18194

There's another encoding that is able to encoding the full range of Unicode

18195

characters: UTF-8. UTF-8 is an 8-bit encoding, which means there are no issues

18196

with byte order in UTF-8. Each byte in a UTF-8 byte sequence consists of two

18197

-parts: Marker bits (the most significant bits) and payload bits. The marker bits

18198

-are a sequence of zero to six 1 bits followed by a 0 bit. Unicode characters are

18199

+parts: marker bits (the most significant bits) and payload bits. The marker bits

18200

+are a sequence of zero to four ``1`` bits followed by a ``0`` bit. Unicode characters are

18201

encoded like this (with x being payload bits, which when concatenated give the

18202

Unicode character):

18203

18204

@@ -824,12 +825,7 @@

18205

+-----------------------------------+----------------------------------------------+

18206

| ``U-00000800`` ... ``U-0000FFFF`` | 1110xxxx 10xxxxxx 10xxxxxx |

18207

+-----------------------------------+----------------------------------------------+

18208

-| ``U-00010000`` ... ``U-001FFFFF`` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |

18209

-+-----------------------------------+----------------------------------------------+

18210

-| ``U-00200000`` ... ``U-03FFFFFF`` | 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx |

18211

-+-----------------------------------+----------------------------------------------+

18212

-| ``U-04000000`` ... ``U-7FFFFFFF`` | 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx |

18213

-| | 10xxxxxx |

18214

+| ``U-00010000`` ... ``U-0010FFFF`` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |

18215

+-----------------------------------+----------------------------------------------+

18216

18217

The least significant bit of the Unicode character is the rightmost x bit.

18218

@@ -854,13 +850,14 @@

18219

| RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK

18220

| INVERTED QUESTION MARK

18221

18222

-in iso-8859-1), this increases the probability that a utf-8-sig encoding can be

18223

+in iso-8859-1), this increases the probability that a ``utf-8-sig`` encoding can be

18224

correctly guessed from the byte sequence. So here the BOM is not used to be able

18225

to determine the byte order used for generating the byte sequence, but as a

18226

signature that helps in guessing the encoding. On encoding the utf-8-sig codec

18227

will write ``0xef``, ``0xbb``, ``0xbf`` as the first three bytes to the file. On

18228

-decoding utf-8-sig will skip those three bytes if they appear as the first three

18229

-bytes in the file.

18230

+decoding ``utf-8-sig`` will skip those three bytes if they appear as the first

18231

+three bytes in the file. In UTF-8, the use of the BOM is discouraged and

18232

+should generally be avoided.

18233

18234

18235

.. _standard-encodings:

18236

diff -r 8527427914a2 Doc/library/collections.rst

18237

--- a/Doc/library/collections.rst

18238

+++ b/Doc/library/collections.rst

18239

@@ -1,4 +1,3 @@

18240

-

18241

:mod:`collections` --- High-performance container datatypes

18242

===========================================================

18243

18244

@@ -15,6 +14,10 @@

18245

import itertools

18246

__name__ = '<doctest>'

18247

18248

+**Source code:** :source:`Lib/collections.py` and :source:`Lib/_abcoll.py`

18249

+

18250

+--------------

18251

+

18252

This module implements specialized container datatypes providing alternatives to

18253

Python's general purpose built-in containers, :class:`dict`, :class:`list`,

18254

:class:`set`, and :class:`tuple`.

18255

@@ -28,13 +31,10 @@

18256

===================== ==================================================================== ===========================

18257

18258

In addition to the concrete container classes, the collections module provides

18259

-:ref:`abstract-base-classes` that can be used to test whether a class provides a

18260

-particular interface, for example, whether it is hashable or a mapping.

18261

+:ref:`abstract base classes <collections-abstract-base-classes>` that can be

18262

+used to test whether a class provides a particular interface, for example,

18263

+whether it is hashable or a mapping.

18264

18265

-.. seealso::

18266

-

18267

- Latest version of the `collections module Python source code

18268

- <http://svn.python.org/view/python/branches/release27-maint/Lib/collections.py?view=markup>`_

18269

18270

:class:`Counter` objects

18271

------------------------

18272

@@ -188,7 +188,7 @@

18273

* The multiset methods are designed only for use cases with positive values.

18274

The inputs may be negative or zero, but only outputs with positive values

18275

are created. There are no type restrictions, but the value type needs to

18276

- support support addition, subtraction, and comparison.

18277

+ support addition, subtraction, and comparison.

18278

18279

* The :meth:`elements` method requires integer counts. It ignores zero and

18280

negative counts.

18281

@@ -202,14 +202,14 @@

18282

* `Bag class <http://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html>`_

18283

in Smalltalk.

18284

18285

- * Wikipedia entry for `Multisets <http://en.wikipedia.org/wiki/Multiset>`_\.

18286

+ * Wikipedia entry for `Multisets <http://en.wikipedia.org/wiki/Multiset>`_.

18287

18288

* `C++ multisets <http://www.demo2s.com/Tutorial/Cpp/0380__set-multiset/Catalog0380__set-multiset.htm>`_

18289

tutorial with examples.

18290

18291

* For mathematical operations on multisets and their use cases, see

18292

*Knuth, Donald. The Art of Computer Programming Volume II,

18293

- Section 4.6.3, Exercise 19*\.

18294

+ Section 4.6.3, Exercise 19*.

18295

18296

* To enumerate all distinct multisets of a given size over a given set of

18297

elements, see :func:`itertools.combinations_with_replacement`.

18298

@@ -453,8 +453,7 @@

18299

:class:`defaultdict` objects support the following method in addition to the

18300

standard :class:`dict` operations:

18301

18302

-

18303

- .. method:: defaultdict.__missing__(key)

18304

+ .. method:: __missing__(key)

18305

18306

If the :attr:`default_factory` attribute is ``None``, this raises a

18307

:exc:`KeyError` exception with the *key* as argument.

18308

@@ -470,11 +469,16 @@

18309

:class:`dict` class when the requested key is not found; whatever it

18310

returns or raises is then returned or raised by :meth:`__getitem__`.

18311

18312

+ Note that :meth:`__missing__` is *not* called for any operations besides

18313

+ :meth:`__getitem__`. This means that :meth:`get` will, like normal

18314

+ dictionaries, return ``None`` as a default rather than using

18315

+ :attr:`default_factory`.

18316

+

18317

18318

:class:`defaultdict` objects support the following instance variable:

18319

18320

18321

- .. attribute:: defaultdict.default_factory

18322

+ .. attribute:: default_factory

18323

18324

This attribute is used by the :meth:`__missing__` method; it is

18325

initialized from the first argument to the constructor, if present, or to

18326

@@ -623,7 +627,9 @@

18327

'Return a new OrderedDict which maps field names to their values'

18328

return OrderedDict(zip(self._fields, self))

18329

18330

- def _replace(_self, **kwds):

18331

+ __dict__ = property(_asdict)

18332

+ <BLANKLINE>

18333

+ def _replace(_self, **kwds):

18334

'Return a new Point object replacing specified fields with new values'

18335

result = _self._make(map(kwds.pop, ('x', 'y'), _self))

18336

if kwds:

18337

@@ -849,14 +855,14 @@

18338

original insertion position is changed and moved to the end::

18339

18340

class LastUpdatedOrderedDict(OrderedDict):

18341

+ 'Store items in the order the keys were last added'

18342

18343

- 'Store items in the order the keys were last added'

18344

def __setitem__(self, key, value):

18345

if key in self:

18346

del self[key]

18347

OrderedDict.__setitem__(self, key, value)

18348

18349

-An ordered dictionary can combined with the :class:`Counter` class

18350

+An ordered dictionary can be combined with the :class:`Counter` class

18351

so that the counter remembers the order elements are first encountered::

18352

18353

class OrderedCounter(Counter, OrderedDict):

18354

@@ -869,10 +875,10 @@

18355

return self.__class__, (OrderedDict(self),)

18356

18357

18358

-.. _abstract-base-classes:

18359

+.. _collections-abstract-base-classes:

18360

18361

-ABCs - abstract base classes

18362

-----------------------------

18363

+Collections Abstract Base Classes

18364

+---------------------------------

18365

18366

The collections module offers the following :term:`ABCs <abstract base class>`:

18367

18368

@@ -886,7 +892,7 @@

18369

:class:`Sized` ``__len__``

18370

:class:`Callable` ``__call__``

18371

18372

-:class:`Sequence` :class:`Sized`, ``__getitem__`` ``__contains__``. ``__iter__``, ``__reversed__``,

18373

+:class:`Sequence` :class:`Sized`, ``__getitem__`` ``__contains__``, ``__iter__``, ``__reversed__``,

18374

:class:`Iterable`, ``index``, and ``count``

18375

:class:`Container`

18376

18377

@@ -1021,9 +1027,6 @@

18378

18379

.. seealso::

18380

18381

- * Latest version of the `Python source code for the collections abstract base classes

18382

- <http://svn.python.org/view/python/branches/release27-maint/Lib/_abcoll.py?view=markup>`_

18383

-

18384

* `OrderedSet recipe <http://code.activestate.com/recipes/576694/>`_ for an

18385

example built on :class:`MutableSet`.

18386

18387

diff -r 8527427914a2 Doc/library/colorsys.rst

18388

--- a/Doc/library/colorsys.rst

18389

+++ b/Doc/library/colorsys.rst

18390

@@ -5,6 +5,9 @@

18391

:synopsis: Conversion functions between RGB and other color systems.

18392

.. sectionauthor:: David Ascher <da@python.net>

18393

18394

+**Source code:** :source:`Lib/colorsys.py`

18395

+

18396

+--------------

18397

18398

The :mod:`colorsys` module defines bidirectional conversions of color values

18399

between colors expressed in the RGB (Red Green Blue) color space used in

18400

diff -r 8527427914a2 Doc/library/commands.rst

18401

--- a/Doc/library/commands.rst

18402

+++ b/Doc/library/commands.rst

18403

@@ -38,7 +38,7 @@

18404

``(status, output)``. *cmd* is actually run as ``{ cmd ; } 2>&1``, so that the

18405

returned output will contain output or error messages. A trailing newline is

18406

stripped from the output. The exit status for the command can be interpreted

18407

- according to the rules for the C function :cfunc:`wait`.

18408

+ according to the rules for the C function :c:func:`wait`.

18409

18410

18411

.. function:: getoutput(cmd)

18412

diff -r 8527427914a2 Doc/library/constants.rst

18413

--- a/Doc/library/constants.rst

18414

+++ b/Doc/library/constants.rst

18415

@@ -1,3 +1,5 @@

18416

+.. _built-in-consts:

18417

+

18418

Built-in Constants

18419

==================

18420

18421

diff -r 8527427914a2 Doc/library/contextlib.rst

18422

--- a/Doc/library/contextlib.rst

18423

+++ b/Doc/library/contextlib.rst

18424

@@ -7,15 +7,14 @@

18425

18426

.. versionadded:: 2.5

18427

18428

+**Source code:** :source:`Lib/contextlib.py`

18429

+

18430

+--------------

18431

+

18432

This module provides utilities for common tasks involving the :keyword:`with`

18433

statement. For more information see also :ref:`typecontextmanager` and

18434

:ref:`context-managers`.

18435

18436

-.. seealso::

18437

-

18438

- Latest version of the `contextlib Python source code

18439

- <http://svn.python.org/view/python/branches/release27-maint/Lib/contextlib.py?view=markup>`_

18440

-

18441

Functions provided:

18442

18443

18444

diff -r 8527427914a2 Doc/library/cookie.rst

18445

--- a/Doc/library/cookie.rst

18446

+++ b/Doc/library/cookie.rst

18447

@@ -11,6 +11,9 @@

18448

3.0. The :term:`2to3` tool will automatically adapt imports when converting

18449

your sources to 3.0.

18450

18451

+**Source code:** :source:`Lib/Cookie.py`

18452

+

18453

+--------------

18454

18455

The :mod:`Cookie` module defines classes for abstracting the concept of

18456

cookies, an HTTP state management mechanism. It supports both simple string-only

18457

@@ -191,7 +194,7 @@

18458

18459

.. method:: Morsel.set(key, value, coded_value)

18460

18461

- Set the *key*, *value* and *coded_value* members.

18462

+ Set the *key*, *value* and *coded_value* attributes.

18463

18464

18465

.. method:: Morsel.isReservedKey(K)

18466

diff -r 8527427914a2 Doc/library/cookielib.rst

18467

--- a/Doc/library/cookielib.rst

18468

+++ b/Doc/library/cookielib.rst

18469

@@ -11,10 +11,11 @@

18470

Python 3.0. The :term:`2to3` tool will automatically adapt imports when

18471

converting your sources to 3.0.

18472

18473

-

18474

.. versionadded:: 2.4

18475

18476

+**Source code:** :source:`Lib/cookielib.py`

18477

18478

+--------------

18479

18480

The :mod:`cookielib` module defines classes for automatic handling of HTTP

18481

cookies. It is useful for accessing web sites that require small pieces of data

18482

diff -r 8527427914a2 Doc/library/copy.rst

18483

--- a/Doc/library/copy.rst

18484

+++ b/Doc/library/copy.rst

18485

@@ -4,7 +4,11 @@

18486

.. module:: copy

18487

:synopsis: Shallow and deep copy operations.

18488

18489

-This module provides generic (shallow and deep) copying operations.

18490

+Assignment statements in Python do not copy objects, they create bindings

18491

+between a target and an object. For collections that are mutable or contain

18492

+mutable items, a copy is sometimes needed so one can change one copy without

18493

+changing the other. This module provides generic shallow and deep copy

18494

+operations (explained below).

18495

18496

18497

Interface summary:

18498

diff -r 8527427914a2 Doc/library/crypto.rst

18499

--- a/Doc/library/crypto.rst

18500

+++ b/Doc/library/crypto.rst

18501

@@ -27,5 +27,5 @@

18502

A.M. Kuchling of further interest; the package contains modules for various

18503

encryption algorithms, most notably AES. These modules are not distributed with

18504

Python but available separately. See the URL

18505

-http://www.amk.ca/python/code/crypto.html for more information.

18506

+http://www.pycrypto.org for more information.

18507

18508

diff -r 8527427914a2 Doc/library/ctypes.rst

18509

--- a/Doc/library/ctypes.rst

18510

+++ b/Doc/library/ctypes.rst

18511

@@ -40,7 +40,7 @@

18512

loads libraries which export functions using the standard ``cdecl`` calling

18513

convention, while *windll* libraries call functions using the ``stdcall``

18514

calling convention. *oledll* also uses the ``stdcall`` calling convention, and

18515

-assumes the functions return a Windows :ctype:`HRESULT` error code. The error

18516

+assumes the functions return a Windows :c:type:`HRESULT` error code. The error

18517

code is used to automatically raise a :class:`WindowsError` exception when the

18518

function call fails.

18519

18520

@@ -201,9 +201,9 @@

18521

``None``, integers, longs, byte strings and unicode strings are the only native

18522

Python objects that can directly be used as parameters in these function calls.

18523

``None`` is passed as a C ``NULL`` pointer, byte strings and unicode strings are

18524

-passed as pointer to the memory block that contains their data (:ctype:`char *`

18525

-or :ctype:`wchar_t *`). Python integers and Python longs are passed as the

18526

-platforms default C :ctype:`int` type, their value is masked to fit into the C

18527

+passed as pointer to the memory block that contains their data (:c:type:`char *`

18528

+or :c:type:`wchar_t *`). Python integers and Python longs are passed as the

18529

+platforms default C :c:type:`int` type, their value is masked to fit into the C

18530

type.

18531

18532

Before we move on calling functions with other parameter types, we have to learn

18533

@@ -217,48 +217,48 @@

18534

18535

:mod:`ctypes` defines a number of primitive C compatible data types :

18536

18537

-+----------------------+----------------------------------------+----------------------------+

18538

-| ctypes type | C type | Python type |

18539

-+======================+========================================+============================+

18540

-| :class:`c_bool` | :ctype:`_Bool` | bool (1) |

18541

-+----------------------+----------------------------------------+----------------------------+

18542

-| :class:`c_char` | :ctype:`char` | 1-character string |

18543

-+----------------------+----------------------------------------+----------------------------+

18544

-| :class:`c_wchar` | :ctype:`wchar_t` | 1-character unicode string |

18545

-+----------------------+----------------------------------------+----------------------------+

18546

-| :class:`c_byte` | :ctype:`char` | int/long |

18547

-+----------------------+----------------------------------------+----------------------------+

18548

-| :class:`c_ubyte` | :ctype:`unsigned char` | int/long |

18549

-+----------------------+----------------------------------------+----------------------------+

18550

-| :class:`c_short` | :ctype:`short` | int/long |

18551

-+----------------------+----------------------------------------+----------------------------+

18552

-| :class:`c_ushort` | :ctype:`unsigned short` | int/long |

18553

-+----------------------+----------------------------------------+----------------------------+

18554

-| :class:`c_int` | :ctype:`int` | int/long |

18555

-+----------------------+----------------------------------------+----------------------------+

18556

-| :class:`c_uint` | :ctype:`unsigned int` | int/long |

18557

-+----------------------+----------------------------------------+----------------------------+

18558

-| :class:`c_long` | :ctype:`long` | int/long |

18559

-+----------------------+----------------------------------------+----------------------------+

18560

-| :class:`c_ulong` | :ctype:`unsigned long` | int/long |

18561

-+----------------------+----------------------------------------+----------------------------+

18562

-| :class:`c_longlong` | :ctype:`__int64` or :ctype:`long long` | int/long |

18563

-+----------------------+----------------------------------------+----------------------------+

18564

-| :class:`c_ulonglong` | :ctype:`unsigned __int64` or | int/long |

18565

-| | :ctype:`unsigned long long` | |

18566

-+----------------------+----------------------------------------+----------------------------+

18567

-| :class:`c_float` | :ctype:`float` | float |

18568

-+----------------------+----------------------------------------+----------------------------+

18569

-| :class:`c_double` | :ctype:`double` | float |

18570

-+----------------------+----------------------------------------+----------------------------+

18571

-| :class:`c_longdouble`| :ctype:`long double` | float |

18572

-+----------------------+----------------------------------------+----------------------------+

18573

-| :class:`c_char_p` | :ctype:`char *` (NUL terminated) | string or ``None`` |

18574

-+----------------------+----------------------------------------+----------------------------+

18575

-| :class:`c_wchar_p` | :ctype:`wchar_t *` (NUL terminated) | unicode or ``None`` |

18576

-+----------------------+----------------------------------------+----------------------------+

18577

-| :class:`c_void_p` | :ctype:`void *` | int/long or ``None`` |

18578

-+----------------------+----------------------------------------+----------------------------+

18579

++----------------------+------------------------------------------+----------------------------+

18580

+| ctypes type | C type | Python type |

18581

++======================+==========================================+============================+

18582

+| :class:`c_bool` | :c:type:`_Bool` | bool (1) |

18583

++----------------------+------------------------------------------+----------------------------+

18584

+| :class:`c_char` | :c:type:`char` | 1-character string |

18585

++----------------------+------------------------------------------+----------------------------+

18586

+| :class:`c_wchar` | :c:type:`wchar_t` | 1-character unicode string |

18587

++----------------------+------------------------------------------+----------------------------+

18588

+| :class:`c_byte` | :c:type:`char` | int/long |

18589

++----------------------+------------------------------------------+----------------------------+

18590

+| :class:`c_ubyte` | :c:type:`unsigned char` | int/long |

18591

++----------------------+------------------------------------------+----------------------------+

18592

+| :class:`c_short` | :c:type:`short` | int/long |

18593

++----------------------+------------------------------------------+----------------------------+

18594

+| :class:`c_ushort` | :c:type:`unsigned short` | int/long |

18595

++----------------------+------------------------------------------+----------------------------+

18596

+| :class:`c_int` | :c:type:`int` | int/long |

18597

++----------------------+------------------------------------------+----------------------------+

18598

+| :class:`c_uint` | :c:type:`unsigned int` | int/long |

18599

++----------------------+------------------------------------------+----------------------------+

18600

+| :class:`c_long` | :c:type:`long` | int/long |

18601

++----------------------+------------------------------------------+----------------------------+

18602

+| :class:`c_ulong` | :c:type:`unsigned long` | int/long |

18603

++----------------------+------------------------------------------+----------------------------+

18604

+| :class:`c_longlong` | :c:type:`__int64` or :c:type:`long long` | int/long |

18605

++----------------------+------------------------------------------+----------------------------+

18606

+| :class:`c_ulonglong` | :c:type:`unsigned __int64` or | int/long |

18607

+| | :c:type:`unsigned long long` | |

18608

++----------------------+------------------------------------------+----------------------------+

18609

+| :class:`c_float` | :c:type:`float` | float |

18610

++----------------------+------------------------------------------+----------------------------+

18611

+| :class:`c_double` | :c:type:`double` | float |

18612

++----------------------+------------------------------------------+----------------------------+

18613

+| :class:`c_longdouble`| :c:type:`long double` | float |

18614

++----------------------+------------------------------------------+----------------------------+

18615

+| :class:`c_char_p` | :c:type:`char *` (NUL terminated) | string or ``None`` |

18616

++----------------------+------------------------------------------+----------------------------+

18617

+| :class:`c_wchar_p` | :c:type:`wchar_t *` (NUL terminated) | unicode or ``None`` |

18618

++----------------------+------------------------------------------+----------------------------+

18619

+| :class:`c_void_p` | :c:type:`void *` | int/long or ``None`` |

18620

++----------------------+------------------------------------------+----------------------------+

18621

18622

(1)

18623

The constructor accepts any object with a truth value.

18624

@@ -329,7 +329,7 @@

18625

The :func:`create_string_buffer` function replaces the :func:`c_buffer` function

18626

(which is still available as an alias), as well as the :func:`c_string` function

18627

from earlier ctypes releases. To create a mutable memory block containing

18628

-unicode characters of the C type :ctype:`wchar_t` use the

18629

+unicode characters of the C type :c:type:`wchar_t` use the

18630

:func:`create_unicode_buffer` function.

18631

18632

18633

@@ -440,7 +440,7 @@

18634

Return types

18635

^^^^^^^^^^^^

18636

18637

-By default functions are assumed to return the C :ctype:`int` type. Other

18638

+By default functions are assumed to return the C :c:type:`int` type. Other

18639

return types can be specified by setting the :attr:`restype` attribute of the

18640

function object.

18641

18642

@@ -869,10 +869,10 @@

18643

18644

struct cell; /* forward declaration */

18645

18646

- struct {

18647

+ struct cell {

18648

char *name;

18649

struct cell *next;

18650

- } cell;

18651

+ };

18652

18653

The straightforward translation into ctypes code would be this, but it does not

18654

work::

18655

@@ -1338,7 +1338,7 @@

18656

18657

Instances of this class represent loaded shared libraries. Functions in these

18658

libraries use the standard C calling convention, and are assumed to return

18659

- :ctype:`int`.

18660

+ :c:type:`int`.

18661

18662

18663

.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)

18664

@@ -1355,7 +1355,7 @@

18665

18666

Windows only: Instances of this class represent loaded shared libraries,

18667

functions in these libraries use the ``stdcall`` calling convention, and are

18668

- assumed to return :ctype:`int` by default.

18669

+ assumed to return :c:type:`int` by default.

18670

18671

On Windows CE only the standard calling convention is used, for convenience the

18672

:class:`WinDLL` and :class:`OleDLL` use the standard calling convention on this

18673

@@ -1500,7 +1500,7 @@

18674

18675

An instance of :class:`PyDLL` that exposes Python C API functions as

18676

attributes. Note that all these functions are assumed to return C

18677

- :ctype:`int`, which is of course not always the truth, so you have to assign

18678

+ :c:type:`int`, which is of course not always the truth, so you have to assign

18679

the correct :attr:`restype` attribute to use these functions.

18680

18681

18682

@@ -1530,10 +1530,10 @@

18683

.. attribute:: restype

18684

18685

Assign a ctypes type to specify the result type of the foreign function.

18686

- Use ``None`` for :ctype:`void`, a function not returning anything.

18687

+ Use ``None`` for :c:type:`void`, a function not returning anything.

18688

18689

It is possible to assign a callable Python object that is not a ctypes

18690

- type, in this case the function is assumed to return a C :ctype:`int`, and

18691

+ type, in this case the function is assumed to return a C :c:type:`int`, and

18692

the callable will be called with this integer, allowing to do further

18693

processing or error checking. Using this is deprecated, for more flexible

18694

post processing or error checking use a ctypes data type as

18695

@@ -2000,7 +2000,7 @@

18696

18697

.. function:: string_at(address[, size])

18698

18699

- This function returns the string starting at memory address address. If size

18700

+ This function returns the string starting at memory address *address*. If size

18701

is specified, it is used as size, otherwise the string is assumed to be

18702

zero-terminated.

18703

18704

@@ -2159,21 +2159,21 @@

18705

18706

.. class:: c_byte

18707

18708

- Represents the C :ctype:`signed char` datatype, and interprets the value as

18709

+ Represents the C :c:type:`signed char` datatype, and interprets the value as

18710

small integer. The constructor accepts an optional integer initializer; no

18711

overflow checking is done.

18712

18713

18714

.. class:: c_char

18715

18716

- Represents the C :ctype:`char` datatype, and interprets the value as a single

18717

+ Represents the C :c:type:`char` datatype, and interprets the value as a single

18718

character. The constructor accepts an optional string initializer, the

18719

length of the string must be exactly one character.

18720

18721

18722

.. class:: c_char_p

18723

18724

- Represents the C :ctype:`char *` datatype when it points to a zero-terminated

18725

+ Represents the C :c:type:`char *` datatype when it points to a zero-terminated

18726

string. For a general character pointer that may also point to binary data,

18727

``POINTER(c_char)`` must be used. The constructor accepts an integer

18728

address, or a string.

18729

@@ -2181,13 +2181,13 @@

18730

18731

.. class:: c_double

18732

18733

- Represents the C :ctype:`double` datatype. The constructor accepts an

18734

+ Represents the C :c:type:`double` datatype. The constructor accepts an

18735

optional float initializer.

18736

18737

18738

.. class:: c_longdouble

18739

18740

- Represents the C :ctype:`long double` datatype. The constructor accepts an

18741

+ Represents the C :c:type:`long double` datatype. The constructor accepts an

18742

optional float initializer. On platforms where ``sizeof(long double) ==

18743

sizeof(double)`` it is an alias to :class:`c_double`.

18744

18745

@@ -2195,150 +2195,150 @@

18746

18747

.. class:: c_float

18748

18749

- Represents the C :ctype:`float` datatype. The constructor accepts an

18750

+ Represents the C :c:type:`float` datatype. The constructor accepts an

18751

optional float initializer.

18752

18753

18754

.. class:: c_int

18755

18756

- Represents the C :ctype:`signed int` datatype. The constructor accepts an

18757

+ Represents the C :c:type:`signed int` datatype. The constructor accepts an

18758

optional integer initializer; no overflow checking is done. On platforms

18759

where ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`.

18760

18761

18762

.. class:: c_int8

18763

18764

- Represents the C 8-bit :ctype:`signed int` datatype. Usually an alias for

18765

+ Represents the C 8-bit :c:type:`signed int` datatype. Usually an alias for

18766

:class:`c_byte`.

18767

18768

18769

.. class:: c_int16

18770

18771

- Represents the C 16-bit :ctype:`signed int` datatype. Usually an alias for

18772

+ Represents the C 16-bit :c:type:`signed int` datatype. Usually an alias for

18773

:class:`c_short`.

18774

18775

18776

.. class:: c_int32

18777

18778

- Represents the C 32-bit :ctype:`signed int` datatype. Usually an alias for

18779

+ Represents the C 32-bit :c:type:`signed int` datatype. Usually an alias for

18780

:class:`c_int`.

18781

18782

18783

.. class:: c_int64

18784

18785

- Represents the C 64-bit :ctype:`signed int` datatype. Usually an alias for

18786

+ Represents the C 64-bit :c:type:`signed int` datatype. Usually an alias for

18787

:class:`c_longlong`.

18788

18789

18790

.. class:: c_long

18791

18792

- Represents the C :ctype:`signed long` datatype. The constructor accepts an

18793

+ Represents the C :c:type:`signed long` datatype. The constructor accepts an

18794

optional integer initializer; no overflow checking is done.

18795

18796

18797

.. class:: c_longlong

18798

18799

- Represents the C :ctype:`signed long long` datatype. The constructor accepts

18800

+ Represents the C :c:type:`signed long long` datatype. The constructor accepts

18801

an optional integer initializer; no overflow checking is done.

18802

18803

18804

.. class:: c_short

18805

18806

- Represents the C :ctype:`signed short` datatype. The constructor accepts an

18807

+ Represents the C :c:type:`signed short` datatype. The constructor accepts an

18808

optional integer initializer; no overflow checking is done.

18809

18810

18811

.. class:: c_size_t

18812

18813

- Represents the C :ctype:`size_t` datatype.

18814

+ Represents the C :c:type:`size_t` datatype.

18815

18816

18817

.. class:: c_ssize_t

18818

18819

- Represents the C :ctype:`ssize_t` datatype.

18820

+ Represents the C :c:type:`ssize_t` datatype.

18821

18822

.. versionadded:: 2.7

18823

18824

18825

.. class:: c_ubyte

18826

18827

- Represents the C :ctype:`unsigned char` datatype, it interprets the value as

18828

+ Represents the C :c:type:`unsigned char` datatype, it interprets the value as

18829

small integer. The constructor accepts an optional integer initializer; no

18830

overflow checking is done.

18831

18832

18833

.. class:: c_uint

18834

18835

- Represents the C :ctype:`unsigned int` datatype. The constructor accepts an

18836

+ Represents the C :c:type:`unsigned int` datatype. The constructor accepts an

18837

optional integer initializer; no overflow checking is done. On platforms

18838

where ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`.

18839

18840

18841

.. class:: c_uint8

18842

18843

- Represents the C 8-bit :ctype:`unsigned int` datatype. Usually an alias for

18844

+ Represents the C 8-bit :c:type:`unsigned int` datatype. Usually an alias for

18845

:class:`c_ubyte`.

18846

18847

18848

.. class:: c_uint16

18849

18850

- Represents the C 16-bit :ctype:`unsigned int` datatype. Usually an alias for

18851

+ Represents the C 16-bit :c:type:`unsigned int` datatype. Usually an alias for

18852

:class:`c_ushort`.

18853

18854

18855

.. class:: c_uint32

18856

18857

- Represents the C 32-bit :ctype:`unsigned int` datatype. Usually an alias for

18858

+ Represents the C 32-bit :c:type:`unsigned int` datatype. Usually an alias for

18859

:class:`c_uint`.

18860

18861

18862

.. class:: c_uint64

18863

18864

- Represents the C 64-bit :ctype:`unsigned int` datatype. Usually an alias for

18865

+ Represents the C 64-bit :c:type:`unsigned int` datatype. Usually an alias for

18866

:class:`c_ulonglong`.

18867

18868

18869

.. class:: c_ulong

18870

18871

- Represents the C :ctype:`unsigned long` datatype. The constructor accepts an

18872

+ Represents the C :c:type:`unsigned long` datatype. The constructor accepts an

18873

optional integer initializer; no overflow checking is done.

18874

18875

18876

.. class:: c_ulonglong

18877

18878

- Represents the C :ctype:`unsigned long long` datatype. The constructor

18879

+ Represents the C :c:type:`unsigned long long` datatype. The constructor

18880

accepts an optional integer initializer; no overflow checking is done.

18881

18882

18883

.. class:: c_ushort

18884

18885

- Represents the C :ctype:`unsigned short` datatype. The constructor accepts

18886

+ Represents the C :c:type:`unsigned short` datatype. The constructor accepts

18887

an optional integer initializer; no overflow checking is done.

18888

18889

18890

.. class:: c_void_p

18891

18892

- Represents the C :ctype:`void *` type. The value is represented as integer.

18893

+ Represents the C :c:type:`void *` type. The value is represented as integer.

18894

The constructor accepts an optional integer initializer.

18895

18896

18897

.. class:: c_wchar

18898

18899

- Represents the C :ctype:`wchar_t` datatype, and interprets the value as a

18900

+ Represents the C :c:type:`wchar_t` datatype, and interprets the value as a

18901

single character unicode string. The constructor accepts an optional string

18902

initializer, the length of the string must be exactly one character.

18903

18904

18905

.. class:: c_wchar_p

18906

18907

- Represents the C :ctype:`wchar_t *` datatype, which must be a pointer to a

18908

+ Represents the C :c:type:`wchar_t *` datatype, which must be a pointer to a

18909

zero-terminated wide character string. The constructor accepts an integer

18910

address, or a string.

18911

18912

18913

.. class:: c_bool

18914

18915

- Represent the C :ctype:`bool` datatype (more accurately, :ctype:`_Bool` from

18916

+ Represent the C :c:type:`bool` datatype (more accurately, :c:type:`_Bool` from

18917

C99). Its value can be True or False, and the constructor accepts any object

18918

that has a truth value.

18919

18920

@@ -2347,18 +2347,18 @@

18921

18922

.. class:: HRESULT

18923

18924

- Windows only: Represents a :ctype:`HRESULT` value, which contains success or

18925

+ Windows only: Represents a :c:type:`HRESULT` value, which contains success or

18926

error information for a function or method call.

18927

18928

18929

.. class:: py_object

18930

18931

- Represents the C :ctype:`PyObject *` datatype. Calling this without an

18932

- argument creates a ``NULL`` :ctype:`PyObject *` pointer.

18933

+ Represents the C :c:type:`PyObject *` datatype. Calling this without an

18934

+ argument creates a ``NULL`` :c:type:`PyObject *` pointer.

18935

18936

The :mod:`ctypes.wintypes` module provides quite some other Windows specific

18937

-data types, for example :ctype:`HWND`, :ctype:`WPARAM`, or :ctype:`DWORD`. Some

18938

-useful structures like :ctype:`MSG` or :ctype:`RECT` are also defined.

18939

+data types, for example :c:type:`HWND`, :c:type:`WPARAM`, or :c:type:`DWORD`. Some

18940

+useful structures like :c:type:`MSG` or :c:type:`RECT` are also defined.

18941

18942

18943

.. _ctypes-structured-data-types:

18944

diff -r 8527427914a2 Doc/library/curses.rst

18945

--- a/Doc/library/curses.rst

18946

+++ b/Doc/library/curses.rst

18947

@@ -44,10 +44,6 @@

18948

Module :mod:`curses.textpad`

18949

Editable text widget for curses supporting :program:`Emacs`\ -like bindings.

18950

18951

- Module :mod:`curses.wrapper`

18952

- Convenience function to ensure proper terminal setup and resetting on

18953

- application entry and exit.

18954

-

18955

:ref:`curses-howto`

18956

Tutorial material on using curses with Python, by Andrew Kuchling and Eric

18957

Raymond.

18958

@@ -79,7 +75,7 @@

18959

18960

.. function:: baudrate()

18961

18962

- Returns the output speed of the terminal in bits per second. On software

18963

+ Return the output speed of the terminal in bits per second. On software

18964

terminal emulators it will have a fixed high value. Included for historical

18965

reasons; in former times, it was used to write output loops for time delays and

18966

occasionally to change interfaces depending on the line speed.

18967

@@ -92,7 +88,7 @@

18968

18969

.. function:: can_change_color()

18970

18971

- Returns true or false, depending on whether the programmer can change the colors

18972

+ Return ``True`` or ``False``, depending on whether the programmer can change the colors

18973

displayed by the terminal.

18974

18975

18976

@@ -107,7 +103,7 @@

18977

18978

.. function:: color_content(color_number)

18979

18980

- Returns the intensity of the red, green, and blue (RGB) components in the color

18981

+ Return the intensity of the red, green, and blue (RGB) components in the color

18982

*color_number*, which must be between ``0`` and :const:`COLORS`. A 3-tuple is

18983

returned, containing the R,G,B values for the given color, which will be between

18984

``0`` (no component) and ``1000`` (maximum amount of component).

18985

@@ -115,7 +111,7 @@

18986

18987

.. function:: color_pair(color_number)

18988

18989

- Returns the attribute value for displaying text in the specified color. This

18990

+ Return the attribute value for displaying text in the specified color. This

18991

attribute value can be combined with :const:`A_STANDOUT`, :const:`A_REVERSE`,

18992

and the other :const:`A_\*` attributes. :func:`pair_number` is the counterpart

18993

to this function.

18994

@@ -123,7 +119,7 @@

18995

18996

.. function:: curs_set(visibility)

18997

18998

- Sets the cursor state. *visibility* can be set to 0, 1, or 2, for invisible,

18999

+ Set the cursor state. *visibility* can be set to 0, 1, or 2, for invisible,

19000

normal, or very visible. If the terminal supports the visibility requested, the

19001

previous cursor state is returned; otherwise, an exception is raised. On many

19002

terminals, the "visible" mode is an underline cursor and the "very visible" mode

19003

@@ -132,7 +128,7 @@

19004

19005

.. function:: def_prog_mode()

19006

19007

- Saves the current terminal mode as the "program" mode, the mode when the running

19008

+ Save the current terminal mode as the "program" mode, the mode when the running

19009

program is using curses. (Its counterpart is the "shell" mode, for when the

19010

program is not in curses.) Subsequent calls to :func:`reset_prog_mode` will

19011

restore this mode.

19012

@@ -140,7 +136,7 @@

19013

19014

.. function:: def_shell_mode()

19015

19016

- Saves the current terminal mode as the "shell" mode, the mode when the running

19017

+ Save the current terminal mode as the "shell" mode, the mode when the running

19018

program is not using curses. (Its counterpart is the "program" mode, when the

19019

program is using curses capabilities.) Subsequent calls to

19020

:func:`reset_shell_mode` will restore this mode.

19021

@@ -148,7 +144,7 @@

19022

19023

.. function:: delay_output(ms)

19024

19025

- Inserts an *ms* millisecond pause in output.

19026

+ Insert an *ms* millisecond pause in output.

19027

19028

19029

.. function:: doupdate()

19030

@@ -179,7 +175,7 @@

19031

19032

.. function:: erasechar()

19033

19034

- Returns the user's current erase character. Under Unix operating systems this

19035

+ Return the user's current erase character. Under Unix operating systems this

19036

is a property of the controlling tty of the curses program, and is not set by

19037

the curses library itself.

19038

19039

@@ -187,7 +183,7 @@

19040

.. function:: filter()

19041

19042

The :func:`.filter` routine, if used, must be called before :func:`initscr` is

19043

- called. The effect is that, during those calls, LINES is set to 1; the

19044

+ called. The effect is that, during those calls, :envvar:`LINES` is set to 1; the

19045

capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home

19046

string is set to the value of cr. The effect is that the cursor is confined to

19047

the current line, and so are screen updates. This may be used for enabling

19048

@@ -213,7 +209,7 @@

19049

method should be call to retrieve the queued mouse event, represented as a

19050

5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used to distinguish

19051

multiple devices, and *x*, *y*, *z* are the event's coordinates. (*z* is

19052

- currently unused.). *bstate* is an integer value whose bits will be set to

19053

+ currently unused.) *bstate* is an integer value whose bits will be set to

19054

indicate the type of event, and will be the bitwise OR of one or more of the

19055

following constants, where *n* is the button number from 1 to 4:

19056

:const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED`,

19057

@@ -223,32 +219,32 @@

19058

19059

.. function:: getsyx()

19060

19061

- Returns the current coordinates of the virtual screen cursor in y and x. If

19062

+ Return the current coordinates of the virtual screen cursor in y and x. If

19063

leaveok is currently true, then -1,-1 is returned.

19064

19065

19066

.. function:: getwin(file)

19067

19068

- Reads window related data stored in the file by an earlier :func:`putwin` call.

19069

+ Read window related data stored in the file by an earlier :func:`putwin` call.

19070

The routine then creates and initializes a new window using that data, returning

19071

the new window object.

19072

19073

19074

.. function:: has_colors()

19075

19076

- Returns true if the terminal can display colors; otherwise, it returns false.

19077

+ Return ``True`` if the terminal can display colors; otherwise, return ``False``.

19078

19079

19080

.. function:: has_ic()

19081

19082

- Returns true if the terminal has insert- and delete- character capabilities.

19083

+ Return ``True`` if the terminal has insert- and delete-character capabilities.

19084

This function is included for historical reasons only, as all modern software

19085

terminal emulators have such capabilities.

19086

19087

19088

.. function:: has_il()

19089

19090

- Returns true if the terminal has insert- and delete-line capabilities, or can

19091

+ Return ``True`` if the terminal has insert- and delete-line capabilities, or can

19092

simulate them using scrolling regions. This function is included for

19093

historical reasons only, as all modern software terminal emulators have such

19094

capabilities.

19095

@@ -256,7 +252,7 @@

19096

19097

.. function:: has_key(ch)

19098

19099

- Takes a key value *ch*, and returns true if the current terminal type recognizes

19100

+ Take a key value *ch*, and return ``True`` if the current terminal type recognizes

19101

a key with that value.

19102

19103

19104

@@ -265,13 +261,13 @@

19105

Used for half-delay mode, which is similar to cbreak mode in that characters

19106

typed by the user are immediately available to the program. However, after

19107

blocking for *tenths* tenths of seconds, an exception is raised if nothing has

19108

- been typed. The value of *tenths* must be a number between 1 and 255. Use

19109

+ been typed. The value of *tenths* must be a number between ``1`` and ``255``. Use

19110

:func:`nocbreak` to leave half-delay mode.

19111

19112

19113

.. function:: init_color(color_number, r, g, b)

19114

19115

- Changes the definition of a color, taking the number of the color to be changed

19116

+ Change the definition of a color, taking the number of the color to be changed

19117

followed by three RGB values (for the amounts of red, green, and blue

19118

components). The value of *color_number* must be between ``0`` and

19119

:const:`COLORS`. Each of *r*, *g*, *b*, must be a value between ``0`` and

19120

@@ -282,7 +278,7 @@

19121

19122

.. function:: init_pair(pair_number, fg, bg)

19123

19124

- Changes the definition of a color-pair. It takes three arguments: the number of

19125

+ Change the definition of a color-pair. It takes three arguments: the number of

19126

the color-pair to be changed, the foreground color number, and the background

19127

color number. The value of *pair_number* must be between ``1`` and

19128

``COLOR_PAIRS - 1`` (the ``0`` color pair is wired to white on black and cannot

19129

@@ -294,7 +290,7 @@

19130

19131

.. function:: initscr()

19132

19133

- Initialize the library. Returns a :class:`WindowObject` which represents the

19134

+ Initialize the library. Return a :class:`WindowObject` which represents the

19135

whole screen.

19136

19137

.. note::

19138

@@ -303,9 +299,15 @@

19139

cause the interpreter to exit.

19140

19141

19142

+.. function:: is_term_resized(nlines, ncols)

19143

+

19144

+ Return ``True`` if :func:`resize_term` would modify the window structure,

19145

+ ``False`` otherwise.

19146

+

19147

+

19148

.. function:: isendwin()

19149

19150

- Returns true if :func:`endwin` has been called (that is, the curses library has

19151

+ Return ``True`` if :func:`endwin` has been called (that is, the curses library has

19152

been deinitialized).

19153

19154

19155

@@ -321,14 +323,14 @@

19156

19157

.. function:: killchar()

19158

19159

- Returns the user's current line kill character. Under Unix operating systems

19160

+ Return the user's current line kill character. Under Unix operating systems

19161

this is a property of the controlling tty of the curses program, and is not set

19162

by the curses library itself.

19163

19164

19165

.. function:: longname()

19166

19167

- Returns a string containing the terminfo long name field describing the current

19168

+ Return a string containing the terminfo long name field describing the current

19169

terminal. The maximum length of a verbose description is 128 characters. It is

19170

defined only after the call to :func:`initscr`.

19171

19172

@@ -341,14 +343,14 @@

19173

19174

.. function:: mouseinterval(interval)

19175

19176

- Sets the maximum time in milliseconds that can elapse between press and release

19177

- events in order for them to be recognized as a click, and returns the previous

19178

+ Set the maximum time in milliseconds that can elapse between press and release

19179

+ events in order for them to be recognized as a click, and return the previous

19180

interval value. The default value is 200 msec, or one fifth of a second.

19181

19182

19183

.. function:: mousemask(mousemask)

19184

19185

- Sets the mouse events to be reported, and returns a tuple ``(availmask,

19186

+ Set the mouse events to be reported, and return a tuple ``(availmask,

19187

oldmask)``. *availmask* indicates which of the specified mouse events can be

19188

reported; on complete failure it returns 0. *oldmask* is the previous value of

19189

the given window's mouse event mask. If this function is never called, no mouse

19190

@@ -362,7 +364,7 @@

19191

19192

.. function:: newpad(nlines, ncols)

19193

19194

- Creates and returns a pointer to a new pad data structure with the given number

19195

+ Create and return a pointer to a new pad data structure with the given number

19196

of lines and columns. A pad is returned as a window object.

19197

19198

A pad is like a window, except that it is not restricted by the screen size, and

19199

@@ -372,9 +374,9 @@

19200

echoing of input) do not occur. The :meth:`refresh` and :meth:`noutrefresh`

19201

methods of a pad require 6 arguments to specify the part of the pad to be

19202

displayed and the location on the screen to be used for the display. The

19203

- arguments are pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; the p

19204

+ arguments are *pminrow*, *pmincol*, *sminrow*, *smincol*, *smaxrow*, *smaxcol*; the *p*

19205

arguments refer to the upper left corner of the pad region to be displayed and

19206

- the s arguments define a clipping box on the screen within which the pad region

19207

+ the *s* arguments define a clipping box on the screen within which the pad region

19208

is to be displayed.

19209

19210

19211

@@ -416,7 +418,7 @@

19212

19213

.. function:: noqiflush()

19214

19215

- When the noqiflush routine is used, normal flush of input and output queues

19216

+ When the :func:`noqiflush` routine is used, normal flush of input and output queues

19217

associated with the INTR, QUIT and SUSP characters will not be done. You may

19218

want to call :func:`noqiflush` in a signal handler if you want output to

19219

continue as though the interrupt had not occurred, after the handler exits.

19220

@@ -429,27 +431,27 @@

19221

19222

.. function:: pair_content(pair_number)

19223

19224

- Returns a tuple ``(fg, bg)`` containing the colors for the requested color pair.

19225

+ Return a tuple ``(fg, bg)`` containing the colors for the requested color pair.

19226

The value of *pair_number* must be between ``1`` and ``COLOR_PAIRS - 1``.

19227

19228

19229

.. function:: pair_number(attr)

19230

19231

- Returns the number of the color-pair set by the attribute value *attr*.

19232

+ Return the number of the color-pair set by the attribute value *attr*.

19233

:func:`color_pair` is the counterpart to this function.

19234

19235

19236

.. function:: putp(string)

19237

19238

- Equivalent to ``tputs(str, 1, putchar)``; emits the value of a specified

19239

- terminfo capability for the current terminal. Note that the output of putp

19240

+ Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified

19241

+ terminfo capability for the current terminal. Note that the output of :func:`putp`

19242

always goes to standard output.

19243

19244

19245

.. function:: qiflush( [flag] )

19246

19247

- If *flag* is false, the effect is the same as calling :func:`noqiflush`. If

19248

- *flag* is true, or no argument is provided, the queues will be flushed when

19249

+ If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. If

19250

+ *flag* is ``True``, or no argument is provided, the queues will be flushed when

19251

these control characters are read.

19252

19253

19254

@@ -462,26 +464,55 @@

19255

19256

.. function:: reset_prog_mode()

19257

19258

- Restores the terminal to "program" mode, as previously saved by

19259

+ Restore the terminal to "program" mode, as previously saved by

19260

:func:`def_prog_mode`.

19261

19262

19263

.. function:: reset_shell_mode()

19264

19265

- Restores the terminal to "shell" mode, as previously saved by

19266

+ Restore the terminal to "shell" mode, as previously saved by

19267

:func:`def_shell_mode`.

19268

19269

19270

+.. function:: resetty()

19271

+

19272

+ Restore the state of the terminal modes to what it was at the last call to

19273

+ :func:`savetty`.

19274

+

19275

+

19276

+.. function:: resize_term(nlines, ncols)

19277

+

19278

+ Backend function used by :func:`resizeterm`, performing most of the work;

19279

+ when resizing the windows, :func:`resize_term` blank-fills the areas that are

19280

+ extended. The calling application should fill in these areas with

19281

+ appropriate data. The :func:`resize_term` function attempts to resize all

19282

+ windows. However, due to the calling convention of pads, it is not possible

19283

+ to resize these without additional interaction with the application.

19284

+

19285

+

19286

+.. function:: resizeterm(nlines, ncols)

19287

+

19288

+ Resize the standard and current windows to the specified dimensions, and

19289

+ adjusts other bookkeeping data used by the curses library that record the

19290

+ window dimensions (in particular the SIGWINCH handler).

19291

+

19292

+

19293

+.. function:: savetty()

19294

+

19295

+ Save the current state of the terminal modes in a buffer, usable by

19296

+ :func:`resetty`.

19297

+

19298

+

19299

.. function:: setsyx(y, x)

19300

19301

- Sets the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then

19302

+ Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then

19303

leaveok is set.

19304

19305

19306

.. function:: setupterm([termstr, fd])

19307

19308

- Initializes the terminal. *termstr* is a string giving the terminal name; if

19309

- omitted, the value of the TERM environment variable will be used. *fd* is the

19310

+ Initialize the terminal. *termstr* is a string giving the terminal name; if

19311

+ omitted, the value of the :envvar:`TERM` environment variable will be used. *fd* is the

19312

file descriptor to which any initialization sequences will be sent; if not

19313

supplied, the file descriptor for ``sys.stdout`` will be used.

19314

19315

@@ -501,19 +532,19 @@

19316

19317

.. function:: termattrs()

19318

19319

- Returns a logical OR of all video attributes supported by the terminal. This

19320

+ Return a logical OR of all video attributes supported by the terminal. This

19321

information is useful when a curses program needs complete control over the

19322

appearance of the screen.

19323

19324

19325

.. function:: termname()

19326

19327

- Returns the value of the environment variable TERM, truncated to 14 characters.

19328

+ Return the value of the environment variable :envvar:`TERM`, truncated to 14 characters.

19329

19330

19331

.. function:: tigetflag(capname)

19332

19333

- Returns the value of the Boolean capability corresponding to the terminfo

19334

+ Return the value of the Boolean capability corresponding to the terminfo

19335

capability name *capname*. The value ``-1`` is returned if *capname* is not a

19336

Boolean capability, or ``0`` if it is canceled or absent from the terminal

19337

description.

19338

@@ -521,7 +552,7 @@

19339

19340

.. function:: tigetnum(capname)

19341

19342

- Returns the value of the numeric capability corresponding to the terminfo

19343

+ Return the value of the numeric capability corresponding to the terminfo

19344

capability name *capname*. The value ``-2`` is returned if *capname* is not a

19345

numeric capability, or ``-1`` if it is canceled or absent from the terminal

19346

description.

19347

@@ -529,22 +560,22 @@

19348

19349

.. function:: tigetstr(capname)

19350

19351

- Returns the value of the string capability corresponding to the terminfo

19352

+ Return the value of the string capability corresponding to the terminfo

19353

capability name *capname*. ``None`` is returned if *capname* is not a string

19354

capability, or is canceled or absent from the terminal description.

19355

19356

19357

.. function:: tparm(str[,...])

19358

19359

- Instantiates the string *str* with the supplied parameters, where *str* should

19360

- be a parameterized string obtained from the terminfo database. E.g.

19361

- ``tparm(tigetstr("cup"), 5, 3)`` could result in ``'\033[6;4H'``, the exact

19362

+ Instantiate the string *str* with the supplied parameters, where *str* should

19363

+ be a parameterized string obtained from the terminfo database. E.g.

19364

+ ``tparm(tigetstr("cup"), 5, 3)`` could result in ``'\033[6;4H'``, the exact

19365

result depending on terminal type.

19366

19367

19368

.. function:: typeahead(fd)

19369

19370

- Specifies that the file descriptor *fd* be used for typeahead checking. If *fd*

19371

+ Specify that the file descriptor *fd* be used for typeahead checking. If *fd*

19372

is ``-1``, then no typeahead checking is done.

19373

19374

The curses library does "line-breakout optimization" by looking for typeahead

19375

@@ -556,7 +587,7 @@

19376

19377

.. function:: unctrl(ch)

19378

19379

- Returns a string which is a printable representation of the character *ch*.

19380

+ Return a string which is a printable representation of the character *ch*.

19381

Control characters are displayed as a caret followed by the character, for

19382

example as ``^C``. Printing characters are left as they are.

19383

19384

@@ -579,7 +610,7 @@

19385

.. function:: use_env(flag)

19386

19387

If used, this function should be called before :func:`initscr` or newterm are

19388

- called. When *flag* is false, the values of lines and columns specified in the

19389

+ called. When *flag* is ``False``, the values of lines and columns specified in the

19390

terminfo database will be used, even if environment variables :envvar:`LINES`

19391

and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a

19392

window (in which case default behavior would be to use the window size if

19393

@@ -595,6 +626,19 @@

19394

foreground color on the default background.

19395

19396

19397

+.. function:: wrapper(func, ...)

19398

+

19399

+ Initialize curses and call another callable object, *func*, which should be the

19400

+ rest of your curses-using application. If the application raises an exception,

19401

+ this function will restore the terminal to a sane state before re-raising the

19402

+ exception and generating a traceback. The callable object *func* is then passed

19403

+ the main window 'stdscr' as its first argument, followed by any other arguments

19404

+ passed to :func:`wrapper`. Before calling *func*, :func:`wrapper` turns on

19405

+ cbreak mode, turns off echo, enables the terminal keypad, and initializes colors

19406

+ if the terminal has color support. On exit (whether normally or by exception)

19407

+ it restores cooked mode, turns on echo, and disables the terminal keypad.

19408

+

19409

+

19410

.. _curses-window-objects:

19411

19412

Window Objects

19413

@@ -608,7 +652,7 @@

19414

19415

.. note::

19416

19417

- A *character* means a C character (an ASCII code), rather then a Python

19418

+ A *character* means a C character (an ASCII code), rather than a Python

19419

character (a string of length 1). (This note is true whenever the

19420

documentation mentions a character.) The built-in :func:`ord` is handy for

19421

conveying strings to codes.

19422

@@ -650,7 +694,7 @@

19423

19424

.. method:: window.bkgd(ch[, attr])

19425

19426

- Sets the background property of the window to the character *ch*, with

19427

+ Set the background property of the window to the character *ch*, with

19428

attributes *attr*. The change is then applied to every character position in

19429

that window:

19430

19431

@@ -663,7 +707,7 @@

19432

19433

.. method:: window.bkgdset(ch[, attr])

19434

19435

- Sets the window's background. A window's background consists of a character and

19436

+ Set the window's background. A window's background consists of a character and

19437

any combination of attributes. The attribute part of the background is combined

19438

(OR'ed) with all non-blank characters that are written into the window. Both

19439

the character and attribute parts of the background are combined with the blank

19440

@@ -708,12 +752,12 @@

19441

.. method:: window.box([vertch, horch])

19442

19443

Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and

19444

- bs are *horch*. The default corner characters are always used by this function.

19445

+ *bs* are *horch*. The default corner characters are always used by this function.

19446

19447

19448

.. method:: window.chgat([y, x, ] [num,] attr)

19449

19450

- Sets the attributes of *num* characters at the current cursor position, or at

19451

+ Set the attributes of *num* characters at the current cursor position, or at

19452

position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1,

19453

the attribute will be set on all the characters to the end of the line. This

19454

function does not move the cursor. The changed line will be touched using the

19455

@@ -723,7 +767,7 @@

19456

19457

.. method:: window.clear()

19458

19459

- Like :meth:`erase`, but also causes the whole window to be repainted upon next

19460

+ Like :meth:`erase`, but also cause the whole window to be repainted upon next

19461

call to :meth:`refresh`.

19462

19463

19464

@@ -746,7 +790,7 @@

19465

19466

.. method:: window.cursyncup()

19467

19468

- Updates the current cursor position of all the ancestors of the window to

19469

+ Update the current cursor position of all the ancestors of the window to

19470

reflect the current cursor position of the window.

19471

19472

19473

@@ -757,14 +801,14 @@

19474

19475

.. method:: window.deleteln()

19476

19477

- Delete the line under the cursor. All following lines are moved up by 1 line.

19478

+ Delete the line under the cursor. All following lines are moved up by one line.

19479

19480

19481

.. method:: window.derwin([nlines, ncols,] begin_y, begin_x)

19482

19483

An abbreviation for "derive window", :meth:`derwin` is the same as calling

19484

:meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origin

19485

- of the window, rather than relative to the entire screen. Returns a window

19486

+ of the window, rather than relative to the entire screen. Return a window

19487

object for the derived window.

19488

19489

19490

@@ -776,8 +820,8 @@

19491

19492

.. method:: window.enclose(y, x)

19493

19494

- Tests whether the given pair of screen-relative character-cell coordinates are

19495

- enclosed by the given window, returning true or false. It is useful for

19496

+ Test whether the given pair of screen-relative character-cell coordinates are

19497

+ enclosed by the given window, returning ``True`` or ``False``. It is useful for

19498

determining what subset of the screen windows enclose the location of a mouse

19499

event.

19500

19501

@@ -792,6 +836,11 @@

19502

Return a tuple ``(y, x)`` of co-ordinates of upper-left corner.

19503

19504

19505

+.. method:: window.getbkgd()

19506

+

19507

+ Return the given window's current background character/attribute pair.

19508

+

19509

+

19510

.. method:: window.getch([y, x])

19511

19512

Get a character. Note that the integer returned does *not* have to be in ASCII

19513

@@ -814,8 +863,8 @@

19514

19515

.. method:: window.getparyx()

19516

19517

- Returns the beginning coordinates of this window relative to its parent window

19518

- into two integer variables y and x. Returns ``-1,-1`` if this window has no

19519

+ Return the beginning coordinates of this window relative to its parent window

19520

+ into two integer variables y and x. Return ``-1, -1`` if this window has no

19521

parent.

19522

19523

19524

@@ -838,8 +887,8 @@

19525

19526

.. method:: window.idcok(flag)

19527

19528

- If *flag* is false, curses no longer considers using the hardware insert/delete

19529

- character feature of the terminal; if *flag* is true, use of character insertion

19530

+ If *flag* is ``False``, curses no longer considers using the hardware insert/delete

19531

+ character feature of the terminal; if *flag* is ``True``, use of character insertion

19532

and deletion is enabled. When curses is first initialized, use of character

19533

insert/delete is enabled by default.

19534

19535

@@ -852,7 +901,7 @@

19536

19537

.. method:: window.immedok(flag)

19538

19539

- If *flag* is true, any change in the window image automatically causes the

19540

+ If *flag* is ``True``, any change in the window image automatically causes the

19541

window to be refreshed; you no longer have to call :meth:`refresh` yourself.

19542

However, it may degrade performance considerably, due to repeated calls to

19543

wrefresh. This option is disabled by default.

19544

@@ -872,7 +921,7 @@

19545

19546

.. method:: window.insdelln(nlines)

19547

19548

- Inserts *nlines* lines into the specified window above the current line. The

19549

+ Insert *nlines* lines into the specified window above the current line. The

19550

*nlines* bottom lines are lost. For negative *nlines*, delete *nlines* lines

19551

starting with the one under the cursor, and move the remaining lines up. The

19552

bottom *nlines* lines are cleared. The current cursor position remains the

19553

@@ -881,7 +930,7 @@

19554

19555

.. method:: window.insertln()

19556

19557

- Insert a blank line under the cursor. All following lines are moved down by 1

19558

+ Insert a blank line under the cursor. All following lines are moved down by one

19559

line.

19560

19561

19562

@@ -904,23 +953,23 @@

19563

19564

.. method:: window.instr([y, x] [, n])

19565

19566

- Returns a string of characters, extracted from the window starting at the

19567

+ Return a string of characters, extracted from the window starting at the

19568

current cursor position, or at *y*, *x* if specified. Attributes are stripped

19569

- from the characters. If *n* is specified, :meth:`instr` returns return a string

19570

+ from the characters. If *n* is specified, :meth:`instr` returns a string

19571

at most *n* characters long (exclusive of the trailing NUL).

19572

19573

19574

.. method:: window.is_linetouched(line)

19575

19576

- Returns true if the specified line was modified since the last call to

19577

- :meth:`refresh`; otherwise returns false. Raises a :exc:`curses.error`

19578

+ Return ``True`` if the specified line was modified since the last call to

19579

+ :meth:`refresh`; otherwise return ``False``. Raise a :exc:`curses.error`

19580

exception if *line* is not valid for the given window.

19581

19582

19583

.. method:: window.is_wintouched()

19584

19585

- Returns true if the specified window was modified since the last call to

19586

- :meth:`refresh`; otherwise returns false.

19587

+ Return ``True`` if the specified window was modified since the last call to

19588

+ :meth:`refresh`; otherwise return ``False``.

19589

19590

19591

.. method:: window.keypad(yes)

19592

@@ -946,7 +995,7 @@

19593

19594

.. method:: window.mvderwin(y, x)

19595

19596

- Moves the window inside its parent window. The screen-relative parameters of

19597

+ Move the window inside its parent window. The screen-relative parameters of

19598

the window are not changed. This routine is used to display different parts of

19599

the parent window at the same physical position on the screen.

19600

19601

@@ -1004,19 +1053,19 @@

19602

19603

.. method:: window.putwin(file)

19604

19605

- Writes all data associated with the window into the provided file object. This

19606

+ Write all data associated with the window into the provided file object. This

19607

information can be later retrieved using the :func:`getwin` function.

19608

19609

19610

.. method:: window.redrawln(beg, num)

19611

19612

- Indicates that the *num* screen lines, starting at line *beg*, are corrupted and

19613

+ Indicate that the *num* screen lines, starting at line *beg*, are corrupted and

19614

should be completely redrawn on the next :meth:`refresh` call.

19615

19616

19617

.. method:: window.redrawwin()

19618

19619

- Touches the entire window, causing it to be completely redrawn on the next

19620

+ Touch the entire window, causing it to be completely redrawn on the next

19621

:meth:`refresh` call.

19622

19623

19624

@@ -1037,6 +1086,14 @@

19625

*sminrow*, or *smincol* are treated as if they were zero.

19626

19627

19628

+.. method:: window.resize(nlines, ncols)

19629

+

19630

+ Reallocate storage for a curses window to adjust its dimensions to the

19631

+ specified values. If either dimension is larger than the current values, the

19632

+ window's data is filled with blanks that have the current background

19633

+ rendition (as set by :meth:`bkgdset`) merged into them.

19634

+

19635

+

19636

.. method:: window.scroll([lines=1])

19637

19638

Scroll the screen or scrolling region upward by *lines* lines.

19639

@@ -1044,7 +1101,7 @@

19640

19641

.. method:: window.scrollok(flag)

19642

19643

- Controls what happens when the cursor of a window is moved off the edge of the

19644

+ Control what happens when the cursor of a window is moved off the edge of the

19645

window or scrolling region, either as a result of a newline action on the bottom

19646

line, or typing the last character of the last line. If *flag* is false, the

19647

cursor is left on the bottom line. If *flag* is true, the window is scrolled up

19648

@@ -1086,26 +1143,26 @@

19649

19650

.. method:: window.syncdown()

19651

19652

- Touches each location in the window that has been touched in any of its ancestor

19653

+ Touch each location in the window that has been touched in any of its ancestor

19654

windows. This routine is called by :meth:`refresh`, so it should almost never

19655

be necessary to call it manually.

19656

19657

19658

.. method:: window.syncok(flag)

19659

19660

- If called with *flag* set to true, then :meth:`syncup` is called automatically

19661

+ If called with *flag* set to ``True``, then :meth:`syncup` is called automatically

19662

whenever there is a change in the window.

19663

19664

19665

.. method:: window.syncup()

19666

19667

- Touches all locations in ancestors of the window that have been changed in the

19668

+ Touch all locations in ancestors of the window that have been changed in the

19669

window.

19670

19671

19672

.. method:: window.timeout(delay)

19673

19674

- Sets blocking or non-blocking read behavior for the window. If *delay* is

19675

+ Set blocking or non-blocking read behavior for the window. If *delay* is

19676

negative, blocking read is used (which will wait indefinitely for input). If

19677

*delay* is zero, then non-blocking read is used, and -1 will be returned by

19678

:meth:`getch` if no input is waiting. If *delay* is positive, then

19679

@@ -1128,7 +1185,7 @@

19680

19681

.. method:: window.untouchwin()

19682

19683

- Marks all lines in the window as unchanged since the last call to

19684

+ Mark all lines in the window as unchanged since the last call to

19685

:meth:`refresh`.

19686

19687

19688

@@ -1587,7 +1644,7 @@

19689

each keystroke entered with the keystroke as a parameter; command dispatch

19690

is done on the result. This method returns the window contents as a

19691

string; whether blanks in the window are included is affected by the

19692

- :attr:`stripspaces` member.

19693

+ :attr:`stripspaces` attribute.

19694

19695

19696

.. method:: do_command(ch)

19697

@@ -1653,45 +1710,15 @@

19698

19699

.. method:: gather()

19700

19701

- This method returns the window contents as a string; whether blanks in the

19702

+ Return the window contents as a string; whether blanks in the

19703

window are included is affected by the :attr:`stripspaces` member.

19704

19705

19706

.. attribute:: stripspaces

19707

19708

- This data member is a flag which controls the interpretation of blanks in

19709

+ This attribute is a flag which controls the interpretation of blanks in

19710

the window. When it is on, trailing blanks on each line are ignored; any

19711

cursor motion that would land the cursor on a trailing blank goes to the

19712

end of that line instead, and trailing blanks are stripped when the window

19713

contents are gathered.

19714

19715

-

19716

-:mod:`curses.wrapper` --- Terminal handler for curses programs

19717

-==============================================================

19718

-

19719

-.. module:: curses.wrapper

19720

- :synopsis: Terminal configuration wrapper for curses programs.

19721

-.. moduleauthor:: Eric Raymond <esr@thyrsus.com>

19722

-.. sectionauthor:: Eric Raymond <esr@thyrsus.com>

19723

-

19724

-

19725

-.. versionadded:: 1.6

19726

-

19727

-This module supplies one function, :func:`wrapper`, which runs another function

19728

-which should be the rest of your curses-using application. If the application

19729

-raises an exception, :func:`wrapper` will restore the terminal to a sane state

19730

-before re-raising the exception and generating a traceback.

19731

-

19732

-

19733

-.. function:: wrapper(func, ...)

19734

-

19735

- Wrapper function that initializes curses and calls another function, *func*,

19736

- restoring normal keyboard/screen behavior on error. The callable object *func*

19737

- is then passed the main window 'stdscr' as its first argument, followed by any

19738

- other arguments passed to :func:`wrapper`.

19739

-

19740

-Before calling the hook function, :func:`wrapper` turns on cbreak mode, turns

19741

-off echo, enables the terminal keypad, and initializes colors if the terminal

19742

-has color support. On exit (whether normally or by exception) it restores

19743

-cooked mode, turns on echo, and disables the terminal keypad.

19744

-

19745

diff -r 8527427914a2 Doc/library/datetime.rst

19746

--- a/Doc/library/datetime.rst

19747

+++ b/Doc/library/datetime.rst

19748

@@ -13,7 +13,7 @@

19749

19750

The :mod:`datetime` module supplies classes for manipulating dates and times in

19751

both simple and complex ways. While date and time arithmetic is supported, the

19752

-focus of the implementation is on efficient member extraction for output

19753

+focus of the implementation is on efficient attribute extraction for output

19754

formatting and manipulation. For related

19755

functionality, see also the :mod:`time` and :mod:`calendar` modules.

19756

19757

@@ -27,8 +27,8 @@

19758

work with, at the cost of ignoring some aspects of reality.

19759

19760

For applications requiring more, :class:`datetime` and :class:`time` objects

19761

-have an optional time zone information member, :attr:`tzinfo`, that can contain

19762

-an instance of a subclass of the abstract :class:`tzinfo` class. These

19763

+have an optional time zone information attribute, :attr:`tzinfo`, that can be

19764

+set to an instance of a subclass of the abstract :class:`tzinfo` class. These

19765

:class:`tzinfo` objects capture information about the offset from UTC time, the

19766

time zone name, and whether Daylight Saving Time is in effect. Note that no

19767

concrete :class:`tzinfo` classes are supplied by the :mod:`datetime` module.

19768

@@ -360,7 +360,7 @@

19769

19770

Return the local date corresponding to the POSIX timestamp, such as is returned

19771

by :func:`time.time`. This may raise :exc:`ValueError`, if the timestamp is out

19772

- of the range of values supported by the platform C :cfunc:`localtime` function.

19773

+ of the range of values supported by the platform C :c:func:`localtime` function.

19774

It's common for this to be restricted to years from 1970 through 2038. Note

19775

that on non-POSIX systems that include leap seconds in their notion of a

19776

timestamp, leap seconds are ignored by :meth:`fromtimestamp`.

19777

@@ -463,9 +463,9 @@

19778

19779

.. method:: date.replace(year, month, day)

19780

19781

- Return a date with the same value, except for those members given new values by

19782

- whichever keyword arguments are specified. For example, if ``d == date(2002,

19783

- 12, 31)``, then ``d.replace(day=26) == date(2002, 12, 26)``.

19784

+ Return a date with the same value, except for those parameters given new

19785

+ values by whichever keyword arguments are specified. For example, if ``d ==

19786

+ date(2002, 12, 31)``, then ``d.replace(day=26) == date(2002, 12, 26)``.

19787

19788

19789

.. method:: date.timetuple()

19790

@@ -534,7 +534,7 @@

19791

Return a string representing the date, for example ``date(2002, 12,

19792

4).ctime() == 'Wed Dec 4 00:00:00 2002'``. ``d.ctime()`` is equivalent to

19793

``time.ctime(time.mktime(d.timetuple()))`` on platforms where the native C

19794

- :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which

19795

+ :c:func:`ctime` function (which :func:`time.ctime` invokes, but which

19796

:meth:`date.ctime` does not invoke) conforms to the C standard.

19797

19798

19799

@@ -641,7 +641,7 @@

19800

or not specified, this is like :meth:`today`, but, if possible, supplies more

19801

precision than can be gotten from going through a :func:`time.time` timestamp

19802

(for example, this may be possible on platforms supplying the C

19803

- :cfunc:`gettimeofday` function).

19804

+ :c:func:`gettimeofday` function).

19805

19806

Else *tz* must be an instance of a class :class:`tzinfo` subclass, and the

19807

current date and time are converted to *tz*'s time zone. In this case the

19808

@@ -669,8 +669,8 @@

19809

``tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz))``.

19810

19811

:meth:`fromtimestamp` may raise :exc:`ValueError`, if the timestamp is out of

19812

- the range of values supported by the platform C :cfunc:`localtime` or

19813

- :cfunc:`gmtime` functions. It's common for this to be restricted to years in

19814

+ the range of values supported by the platform C :c:func:`localtime` or

19815

+ :c:func:`gmtime` functions. It's common for this to be restricted to years in

19816

1970 through 2038. Note that on non-POSIX systems that include leap seconds in

19817

their notion of a timestamp, leap seconds are ignored by :meth:`fromtimestamp`,

19818

and then it's possible to have two timestamps differing by a second that yield

19819

@@ -681,7 +681,7 @@

19820

19821

Return the UTC :class:`datetime` corresponding to the POSIX timestamp, with

19822

:attr:`tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is

19823

- out of the range of values supported by the platform C :cfunc:`gmtime` function.

19824

+ out of the range of values supported by the platform C :c:func:`gmtime` function.

19825

It's common for this to be restricted to years in 1970 through 2038. See also

19826

:meth:`fromtimestamp`.

19827

19828

@@ -696,11 +696,13 @@

19829

19830

.. classmethod:: datetime.combine(date, time)

19831

19832

- Return a new :class:`datetime` object whose date members are equal to the given

19833

- :class:`date` object's, and whose time and :attr:`tzinfo` members are equal to

19834

- the given :class:`time` object's. For any :class:`datetime` object *d*, ``d ==

19835

- datetime.combine(d.date(), d.timetz())``. If date is a :class:`datetime`

19836

- object, its time and :attr:`tzinfo` members are ignored.

19837

+ Return a new :class:`datetime` object whose date components are equal to the

19838

+ given :class:`date` object's, and whose time components and :attr:`tzinfo`

19839

+ attributes are equal to the given :class:`time` object's. For any

19840

+ :class:`datetime` object *d*,

19841

+ ``d == datetime.combine(d.date(), d.timetz())``. If date is a

19842

+ :class:`datetime` object, its time components and :attr:`tzinfo` attributes

19843

+ are ignored.

19844

19845

19846

.. classmethod:: datetime.strptime(date_string, format)

19847

@@ -795,43 +797,44 @@

19848

(1)

19849

datetime2 is a duration of timedelta removed from datetime1, moving forward in

19850

time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0. The

19851

- result has the same :attr:`tzinfo` member as the input datetime, and datetime2 -

19852

- datetime1 == timedelta after. :exc:`OverflowError` is raised if datetime2.year

19853

- would be smaller than :const:`MINYEAR` or larger than :const:`MAXYEAR`. Note

19854

- that no time zone adjustments are done even if the input is an aware object.

19855

+ result has the same :attr:`tzinfo` attribute as the input datetime, and

19856

+ datetime2 - datetime1 == timedelta after. :exc:`OverflowError` is raised if

19857

+ datetime2.year would be smaller than :const:`MINYEAR` or larger than

19858

+ :const:`MAXYEAR`. Note that no time zone adjustments are done even if the

19859

+ input is an aware object.

19860

19861

(2)

19862

Computes the datetime2 such that datetime2 + timedelta == datetime1. As for

19863

- addition, the result has the same :attr:`tzinfo` member as the input datetime,

19864

- and no time zone adjustments are done even if the input is aware. This isn't

19865

- quite equivalent to datetime1 + (-timedelta), because -timedelta in isolation

19866

- can overflow in cases where datetime1 - timedelta does not.

19867

+ addition, the result has the same :attr:`tzinfo` attribute as the input

19868

+ datetime, and no time zone adjustments are done even if the input is aware.

19869

+ This isn't quite equivalent to datetime1 + (-timedelta), because -timedelta

19870

+ in isolation can overflow in cases where datetime1 - timedelta does not.

19871

19872

(3)

19873

Subtraction of a :class:`datetime` from a :class:`datetime` is defined only if

19874

both operands are naive, or if both are aware. If one is aware and the other is

19875

naive, :exc:`TypeError` is raised.

19876

19877

- If both are naive, or both are aware and have the same :attr:`tzinfo` member,

19878

- the :attr:`tzinfo` members are ignored, and the result is a :class:`timedelta`

19879

+ If both are naive, or both are aware and have the same :attr:`tzinfo` attribute,

19880

+ the :attr:`tzinfo` attributes are ignored, and the result is a :class:`timedelta`

19881

object *t* such that ``datetime2 + t == datetime1``. No time zone adjustments

19882

are done in this case.

19883

19884

- If both are aware and have different :attr:`tzinfo` members, ``a-b`` acts as if

19885

- *a* and *b* were first converted to naive UTC datetimes first. The result is

19886

- ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) -

19887

- b.utcoffset())`` except that the implementation never overflows.

19888

+ If both are aware and have different :attr:`tzinfo` attributes, ``a-b`` acts

19889

+ as if *a* and *b* were first converted to naive UTC datetimes first. The

19890

+ result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None)

19891

+ - b.utcoffset())`` except that the implementation never overflows.

19892

19893

(4)

19894

*datetime1* is considered less than *datetime2* when *datetime1* precedes

19895

*datetime2* in time.

19896

19897

If one comparand is naive and the other is aware, :exc:`TypeError` is raised.

19898

- If both comparands are aware, and have the same :attr:`tzinfo` member, the

19899

- common :attr:`tzinfo` member is ignored and the base datetimes are compared. If

19900

- both comparands are aware and have different :attr:`tzinfo` members, the

19901

- comparands are first adjusted by subtracting their UTC offsets (obtained from

19902

- ``self.utcoffset()``).

19903

+ If both comparands are aware, and have the same :attr:`tzinfo` attribute, the

19904

+ common :attr:`tzinfo` attribute is ignored and the base datetimes are

19905

+ compared. If both comparands are aware and have different :attr:`tzinfo`

19906

+ attributes, the comparands are first adjusted by subtracting their UTC

19907

+ offsets (obtained from ``self.utcoffset()``).

19908

19909

.. note::

19910

19911

@@ -864,22 +867,22 @@

19912

.. method:: datetime.timetz()

19913

19914

Return :class:`time` object with same hour, minute, second, microsecond, and

19915

- tzinfo members. See also method :meth:`time`.

19916

+ tzinfo attributes. See also method :meth:`time`.

19917

19918

19919

.. method:: datetime.replace([year[, month[, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]]]])

19920

19921

- Return a datetime with the same members, except for those members given new

19922

- values by whichever keyword arguments are specified. Note that ``tzinfo=None``

19923

- can be specified to create a naive datetime from an aware datetime with no

19924

- conversion of date and time members.

19925

+ Return a datetime with the same attributes, except for those attributes given

19926

+ new values by whichever keyword arguments are specified. Note that

19927

+ ``tzinfo=None`` can be specified to create a naive datetime from an aware

19928

+ datetime with no conversion of date and time data.

19929

19930

19931

.. method:: datetime.astimezone(tz)

19932

19933

- Return a :class:`datetime` object with new :attr:`tzinfo` member *tz*, adjusting

19934

- the date and time members so the result is the same UTC time as *self*, but in

19935

- *tz*'s local time.

19936

+ Return a :class:`datetime` object with new :attr:`tzinfo` attribute *tz*,

19937

+ adjusting the date and time data so the result is the same UTC time as

19938

+ *self*, but in *tz*'s local time.

19939

19940

*tz* must be an instance of a :class:`tzinfo` subclass, and its

19941

:meth:`utcoffset` and :meth:`dst` methods must not return ``None``. *self* must

19942

@@ -887,18 +890,18 @@

19943

not return ``None``).

19944

19945

If ``self.tzinfo`` is *tz*, ``self.astimezone(tz)`` is equal to *self*: no

19946

- adjustment of date or time members is performed. Else the result is local time

19947

- in time zone *tz*, representing the same UTC time as *self*: after ``astz =

19948

- dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have the same date

19949

- and time members as ``dt - dt.utcoffset()``. The discussion of class

19950

- :class:`tzinfo` explains the cases at Daylight Saving Time transition boundaries

19951

- where this cannot be achieved (an issue only if *tz* models both standard and

19952

- daylight time).

19953

+ adjustment of date or time data is performed. Else the result is local

19954

+ time in time zone *tz*, representing the same UTC time as *self*: after

19955

+ ``astz = dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have

19956

+ the same date and time data as ``dt - dt.utcoffset()``. The discussion

19957

+ of class :class:`tzinfo` explains the cases at Daylight Saving Time transition

19958

+ boundaries where this cannot be achieved (an issue only if *tz* models both

19959

+ standard and daylight time).

19960

19961

If you merely want to attach a time zone object *tz* to a datetime *dt* without

19962

- adjustment of date and time members, use ``dt.replace(tzinfo=tz)``. If you

19963

+ adjustment of date and time data, use ``dt.replace(tzinfo=tz)``. If you

19964

merely want to remove the time zone object from an aware datetime *dt* without

19965

- conversion of date and time members, use ``dt.replace(tzinfo=None)``.

19966

+ conversion of date and time data, use ``dt.replace(tzinfo=None)``.

19967

19968

Note that the default :meth:`tzinfo.fromutc` method can be overridden in a

19969

:class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`.

19970

@@ -1021,7 +1024,7 @@

19971

Return a string representing the date and time, for example ``datetime(2002, 12,

19972

4, 20, 30, 40).ctime() == 'Wed Dec 4 20:30:40 2002'``. ``d.ctime()`` is

19973

equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the

19974

- native C :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which

19975

+ native C :c:func:`ctime` function (which :func:`time.ctime` invokes, but which

19976

:meth:`datetime.ctime` does not invoke) conforms to the C standard.

19977

19978

19979

@@ -1161,19 +1164,19 @@

19980

19981

.. attribute:: time.min

19982

19983

- The earliest representable :class:`time`, ``time(0, 0, 0, 0)``.

19984

+ The earliest representable :class:`.time`, ``time(0, 0, 0, 0)``.

19985

19986

19987

.. attribute:: time.max

19988

19989

- The latest representable :class:`time`, ``time(23, 59, 59, 999999)``.

19990

+ The latest representable :class:`.time`, ``time(23, 59, 59, 999999)``.

19991

19992

19993

.. attribute:: time.resolution

19994

19995

- The smallest possible difference between non-equal :class:`time` objects,

19996

- ``timedelta(microseconds=1)``, although note that arithmetic on :class:`time`

19997

- objects is not supported.

19998

+ The smallest possible difference between non-equal :class:`.time` objects,

19999

+ ``timedelta(microseconds=1)``, although note that arithmetic on

20000

+ :class:`.time` objects is not supported.

20001

20002

20003

Instance attributes (read-only):

20004

@@ -1200,7 +1203,7 @@

20005

20006

.. attribute:: time.tzinfo

20007

20008

- The object passed as the tzinfo argument to the :class:`time` constructor, or

20009

+ The object passed as the tzinfo argument to the :class:`.time` constructor, or

20010

``None`` if none was passed.

20011

20012

20013

@@ -1209,14 +1212,14 @@

20014

* comparison of :class:`time` to :class:`time`, where *a* is considered less

20015

than *b* when *a* precedes *b* in time. If one comparand is naive and the other

20016

is aware, :exc:`TypeError` is raised. If both comparands are aware, and have

20017

- the same :attr:`tzinfo` member, the common :attr:`tzinfo` member is ignored and

20018

- the base times are compared. If both comparands are aware and have different

20019

- :attr:`tzinfo` members, the comparands are first adjusted by subtracting their

20020

- UTC offsets (obtained from ``self.utcoffset()``). In order to stop mixed-type

20021

- comparisons from falling back to the default comparison by object address, when

20022

- a :class:`time` object is compared to an object of a different type,

20023

- :exc:`TypeError` is raised unless the comparison is ``==`` or ``!=``. The

20024

- latter cases return :const:`False` or :const:`True`, respectively.

20025

+ the same :attr:`tzinfo` attribute, the common :attr:`tzinfo` attribute is

20026

+ ignored and the base times are compared. If both comparands are aware and

20027

+ have different :attr:`tzinfo` attributes, the comparands are first adjusted by

20028

+ subtracting their UTC offsets (obtained from ``self.utcoffset()``). In order

20029

+ to stop mixed-type comparisons from falling back to the default comparison by

20030

+ object address, when a :class:`time` object is compared to an object of a

20031

+ different type, :exc:`TypeError` is raised unless the comparison is ``==`` or

20032

+ ``!=``. The latter cases return :const:`False` or :const:`True`, respectively.

20033

20034

* hash, use as dict key

20035

20036

@@ -1231,10 +1234,10 @@

20037

20038

.. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]])

20039

20040

- Return a :class:`time` with the same value, except for those members given new

20041

- values by whichever keyword arguments are specified. Note that ``tzinfo=None``

20042

- can be specified to create a naive :class:`time` from an aware :class:`time`,

20043

- without conversion of the time members.

20044

+ Return a :class:`.time` with the same value, except for those attributes given

20045

+ new values by whichever keyword arguments are specified. Note that

20046

+ ``tzinfo=None`` can be specified to create a naive :class:`.time` from an

20047

+ aware :class:`.time`, without conversion of the time data.

20048

20049

20050

.. method:: time.isoformat()

20051

@@ -1317,7 +1320,7 @@

20052

20053

An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the

20054

constructors for :class:`datetime` and :class:`time` objects. The latter objects

20055

-view their members as being in local time, and the :class:`tzinfo` object

20056

+view their attributes as being in local time, and the :class:`tzinfo` object

20057

supports methods revealing offset of local time from UTC, the name of the time

20058

zone, and DST offset, all relative to a date or time object passed to them.

20059

20060

@@ -1362,9 +1365,9 @@

20061

already been added to the UTC offset returned by :meth:`utcoffset`, so there's

20062

no need to consult :meth:`dst` unless you're interested in obtaining DST info

20063

separately. For example, :meth:`datetime.timetuple` calls its :attr:`tzinfo`

20064

- member's :meth:`dst` method to determine how the :attr:`tm_isdst` flag should be

20065

- set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for DST changes

20066

- when crossing time zones.

20067

+ attribute's :meth:`dst` method to determine how the :attr:`tm_isdst` flag

20068

+ should be set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for

20069

+ DST changes when crossing time zones.

20070

20071

An instance *tz* of a :class:`tzinfo` subclass that models both standard and

20072

daylight times must be consistent in this sense:

20073

@@ -1382,13 +1385,13 @@

20074

20075

Most implementations of :meth:`dst` will probably look like one of these two::

20076

20077

- def dst(self):

20078

+ def dst(self, dt):

20079

# a fixed-offset class: doesn't account for DST

20080

return timedelta(0)

20081

20082

or ::

20083

20084

- def dst(self):

20085

+ def dst(self, dt):

20086

# Code to set dston and dstoff to the time zone's DST

20087

# transition times based on the input dt.year, and expressed

20088

# in standard local time. Then

20089

@@ -1439,11 +1442,11 @@

20090

20091

.. method:: tzinfo.fromutc(self, dt)

20092

20093

- This is called from the default :class:`datetime.astimezone()` implementation.

20094

- When called from that, ``dt.tzinfo`` is *self*, and *dt*'s date and time members

20095

- are to be viewed as expressing a UTC time. The purpose of :meth:`fromutc` is to

20096

- adjust the date and time members, returning an equivalent datetime in *self*'s

20097

- local time.

20098

+ This is called from the default :class:`datetime.astimezone()`

20099

+ implementation. When called from that, ``dt.tzinfo`` is *self*, and *dt*'s

20100

+ date and time data are to be viewed as expressing a UTC time. The purpose

20101

+ of :meth:`fromutc` is to adjust the date and time data, returning an

20102

+ equivalent datetime in *self*'s local time.

20103

20104

Most :class:`tzinfo` subclasses should be able to inherit the default

20105

:meth:`fromutc` implementation without problems. It's strong enough to handle

20106

diff -r 8527427914a2 Doc/library/decimal.rst

20107

--- a/Doc/library/decimal.rst

20108

+++ b/Doc/library/decimal.rst

20109

@@ -35,7 +35,7 @@

20110

people learn at school." -- excerpt from the decimal arithmetic specification.

20111

20112

* Decimal numbers can be represented exactly. In contrast, numbers like

20113

- :const:`1.1` and :const:`2.2` do not have an exact representations in binary

20114

+ :const:`1.1` and :const:`2.2` do not have exact representations in binary

20115

floating point. End users typically would not expect ``1.1 + 2.2`` to display

20116

as :const:`3.3000000000000003` as it does with binary floating point.

20117

20118

@@ -742,7 +742,7 @@

20119

20120

Normalize the number by stripping the rightmost trailing zeros and

20121

converting any result equal to :const:`Decimal('0')` to

20122

- :const:`Decimal('0e0')`. Used for producing canonical values for members

20123

+ :const:`Decimal('0e0')`. Used for producing canonical values for attributes

20124

of an equivalence class. For example, ``Decimal('32.100')`` and

20125

``Decimal('0.321000e+2')`` both normalize to the equivalent value

20126

``Decimal('32.1')``.

20127

diff -r 8527427914a2 Doc/library/dis.rst

20128

--- a/Doc/library/dis.rst

20129

+++ b/Doc/library/dis.rst

20130

@@ -1,21 +1,18 @@

20131

-

20132

:mod:`dis` --- Disassembler for Python bytecode

20133

===============================================

20134

20135

.. module:: dis

20136

:synopsis: Disassembler for Python bytecode.

20137

20138

+**Source code:** :source:`Lib/dis.py`

20139

+

20140

+--------------

20141

20142

The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by

20143

disassembling it. The CPython bytecode which this module takes as an

20144

input is defined in the file :file:`Include/opcode.h` and used by the compiler

20145

and the interpreter.

20146

20147

-.. seealso::

20148

-

20149

- Latest version of the `dis module Python source code

20150

- <http://svn.python.org/view/python/branches/release27-maint/Lib/dis.py?view=markup>`_

20151

-

20152

.. impl-detail::

20153

20154

Bytecode is an implementation detail of the CPython interpreter! No

20155

diff -r 8527427914a2 Doc/library/dl.rst

20156

--- a/Doc/library/dl.rst

20157

+++ b/Doc/library/dl.rst

20158

@@ -13,7 +13,7 @@

20159

20160

.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>

20161

20162

-The :mod:`dl` module defines an interface to the :cfunc:`dlopen` function, which

20163

+The :mod:`dl` module defines an interface to the :c:func:`dlopen` function, which

20164

is the most common interface on Unix platforms for handling dynamically linked

20165

libraries. It allows the program to call arbitrary functions in such a library.

20166

20167

@@ -105,10 +105,10 @@

20168

Call the function named *name* in the referenced shared object. The arguments

20169

must be either Python integers, which will be passed as is, Python strings, to

20170

which a pointer will be passed, or ``None``, which will be passed as *NULL*.

20171

- Note that strings should only be passed to functions as :ctype:`const char\*`,

20172

+ Note that strings should only be passed to functions as :c:type:`const char\*`,

20173

as Python will not like its string mutated.

20174

20175

There must be at most 10 arguments, and arguments not given will be treated as

20176

- ``None``. The function's return value must be a C :ctype:`long`, which is a

20177

+ ``None``. The function's return value must be a C :c:type:`long`, which is a

20178

Python integer.

20179

20180

diff -r 8527427914a2 Doc/library/doctest.rst

20181

--- a/Doc/library/doctest.rst

20182

+++ b/Doc/library/doctest.rst

20183

@@ -1199,12 +1199,11 @@

20184

.. class:: DocTest(examples, globs, name, filename, lineno, docstring)

20185

20186

A collection of doctest examples that should be run in a single namespace. The

20187

- constructor arguments are used to initialize the member variables of the same

20188

- names.

20189

+ constructor arguments are used to initialize the attributes of the same names.

20190

20191

.. versionadded:: 2.4

20192

20193

- :class:`DocTest` defines the following member variables. They are initialized by

20194

+ :class:`DocTest` defines the following attributes. They are initialized by

20195

the constructor, and should not be modified directly.

20196

20197

20198

@@ -1257,12 +1256,12 @@

20199

.. class:: Example(source, want[, exc_msg][, lineno][, indent][, options])

20200

20201

A single interactive example, consisting of a Python statement and its expected

20202

- output. The constructor arguments are used to initialize the member variables

20203

- of the same names.

20204

+ output. The constructor arguments are used to initialize the attributes of the

20205

+ same names.

20206

20207

.. versionadded:: 2.4

20208

20209

- :class:`Example` defines the following member variables. They are initialized by

20210

+ :class:`Example` defines the following attributes. They are initialized by

20211

the constructor, and should not be modified directly.

20212

20213

20214

@@ -1770,9 +1769,9 @@

20215

20216

An exception raised by :class:`DocTestRunner` to signal that a doctest example's

20217

actual output did not match its expected output. The constructor arguments are

20218

- used to initialize the member variables of the same names.

20219

-

20220

-:exc:`DocTestFailure` defines the following member variables:

20221

+ used to initialize the attributes of the same names.

20222

+

20223

+:exc:`DocTestFailure` defines the following attributes:

20224

20225

20226

.. attribute:: DocTestFailure.test

20227

@@ -1794,9 +1793,9 @@

20228

20229

An exception raised by :class:`DocTestRunner` to signal that a doctest

20230

example raised an unexpected exception. The constructor arguments are used

20231

- to initialize the member variables of the same names.

20232

-

20233

-:exc:`UnexpectedException` defines the following member variables:

20234

+ to initialize the attributes of the same names.

20235

+

20236

+:exc:`UnexpectedException` defines the following attributes:

20237

20238

20239

.. attribute:: UnexpectedException.test

20240

diff -r 8527427914a2 Doc/library/dummy_thread.rst

20241

--- a/Doc/library/dummy_thread.rst

20242

+++ b/Doc/library/dummy_thread.rst

20243

@@ -10,6 +10,9 @@

20244

converting your sources to 3.0; however, you should consider using the

20245

high-lever :mod:`dummy_threading` module instead.

20246

20247

+**Source code:** :source:`Lib/dummy_thread.py`

20248

+

20249

+--------------

20250

20251

This module provides a duplicate interface to the :mod:`thread` module. It is

20252

meant to be imported when the :mod:`thread` module is not provided on a

20253

diff -r 8527427914a2 Doc/library/dummy_threading.rst

20254

--- a/Doc/library/dummy_threading.rst

20255

+++ b/Doc/library/dummy_threading.rst

20256

@@ -1,10 +1,12 @@

20257

-

20258

:mod:`dummy_threading` --- Drop-in replacement for the :mod:`threading` module

20259

==============================================================================

20260

20261

.. module:: dummy_threading

20262

:synopsis: Drop-in replacement for the threading module.

20263

20264

+**Source code:** :source:`Lib/dummy_threading.py`

20265

+

20266

+--------------

20267

20268

This module provides a duplicate interface to the :mod:`threading` module. It

20269

is meant to be imported when the :mod:`thread` module is not provided on a

20270

diff -r 8527427914a2 Doc/library/easydialogs.rst

20271

--- a/Doc/library/easydialogs.rst

20272

+++ b/Doc/library/easydialogs.rst

20273

@@ -143,7 +143,7 @@

20274

20275

.. seealso::

20276

20277

- `Navigation Services Reference <http://developer.apple.com/documentation/Carbon/Reference/Navigation_Services_Ref/>`_

20278

+ `Navigation Services Reference <http://developer.apple.com/legacy/mac/library/#documentation/Carbon/Conceptual/NavServicesIntro/ns_intro_carb/ns_into_carb.html>`_

20279

Programmer's reference documentation for the Navigation Services, a part of the

20280

Carbon framework.

20281

20282

diff -r 8527427914a2 Doc/library/email.message.rst

20283

--- a/Doc/library/email.message.rst

20284

+++ b/Doc/library/email.message.rst

20285

@@ -295,7 +295,7 @@

20286

20287

Content-Disposition: attachment; filename="bud.gif"

20288

20289

- An example with with non-ASCII characters::

20290

+ An example with non-ASCII characters::

20291

20292

msg.add_header('Content-Disposition', 'attachment',

20293

filename=('iso-8859-1', '', 'Fußballer.ppt'))

20294

diff -r 8527427914a2 Doc/library/email.mime.rst

20295

--- a/Doc/library/email.mime.rst

20296

+++ b/Doc/library/email.mime.rst

20297

@@ -196,6 +196,6 @@

20298

20299

.. versionchanged:: 2.4

20300

The previously deprecated *_encoding* argument has been removed. Content

20301

- Transfer Encoding now happens happens implicitly based on the *_charset*

20302

+ Transfer Encoding now happens implicitly based on the *_charset*

20303

argument.

20304

20305

diff -r 8527427914a2 Doc/library/email.parser.rst

20306

--- a/Doc/library/email.parser.rst

20307

+++ b/Doc/library/email.parser.rst

20308

@@ -135,7 +135,9 @@

20309

data or by a blank line. Following the header block is the body of the

20310

message (which may contain MIME-encoded subparts).

20311

20312

- Optional *headersonly* is as with the :meth:`parse` method.

20313

+ Optional *headersonly* is a flag specifying whether to stop parsing after

20314

+ reading the headers or not. The default is ``False``, meaning it parses

20315

+ the entire contents of the file.

20316

20317

.. versionchanged:: 2.2.2

20318

The *headersonly* flag was added.

20319

@@ -148,9 +150,7 @@

20320

equivalent to wrapping *text* in a :class:`StringIO` instance first and

20321

calling :meth:`parse`.

20322

20323

- Optional *headersonly* is a flag specifying whether to stop parsing after

20324

- reading the headers or not. The default is ``False``, meaning it parses

20325

- the entire contents of the file.

20326

+ Optional *headersonly* is as with the :meth:`parse` method.

20327

20328

.. versionchanged:: 2.2.2

20329

The *headersonly* flag was added.

20330

diff -r 8527427914a2 Doc/library/exceptions.rst

20331

--- a/Doc/library/exceptions.rst

20332

+++ b/Doc/library/exceptions.rst

20333

@@ -220,7 +220,7 @@

20334

Raised when an operation runs out of memory but the situation may still be

20335

rescued (by deleting some objects). The associated value is a string indicating

20336

what kind of (internal) operation ran out of memory. Note that because of the

20337

- underlying memory management architecture (C's :cfunc:`malloc` function), the

20338

+ underlying memory management architecture (C's :c:func:`malloc` function), the

20339

interpreter may not always be able to completely recover from this situation; it

20340

nevertheless raises an exception so that a stack traceback can be printed, in

20341

case a run-away program was the cause.

20342

@@ -249,8 +249,8 @@

20343

This exception is derived from :exc:`EnvironmentError`. It is raised when a

20344

function returns a system-related error (not for illegal argument types or

20345

other incidental errors). The :attr:`errno` attribute is a numeric error

20346

- code from :cdata:`errno`, and the :attr:`strerror` attribute is the

20347

- corresponding string, as would be printed by the C function :cfunc:`perror`.

20348

+ code from :c:data:`errno`, and the :attr:`strerror` attribute is the

20349

+ corresponding string, as would be printed by the C function :c:func:`perror`.

20350

See the module :mod:`errno`, which contains names for the error codes defined

20351

by the underlying operating system.

20352

20353

@@ -342,7 +342,7 @@

20354

This exception is raised by the :func:`sys.exit` function. When it is not

20355

handled, the Python interpreter exits; no stack traceback is printed. If the

20356

associated value is a plain integer, it specifies the system exit status (passed

20357

- to C's :cfunc:`exit` function); if it is ``None``, the exit status is zero; if

20358

+ to C's :c:func:`exit` function); if it is ``None``, the exit status is zero; if

20359

it has another type (such as a string), the object's value is printed and the

20360

exit status is one.

20361

20362

@@ -429,16 +429,16 @@

20363

.. exception:: WindowsError

20364

20365

Raised when a Windows-specific error occurs or when the error number does not

20366

- correspond to an :cdata:`errno` value. The :attr:`winerror` and

20367

+ correspond to an :c:data:`errno` value. The :attr:`winerror` and

20368

:attr:`strerror` values are created from the return values of the

20369

- :cfunc:`GetLastError` and :cfunc:`FormatMessage` functions from the Windows

20370

+ :c:func:`GetLastError` and :c:func:`FormatMessage` functions from the Windows

20371

Platform API. The :attr:`errno` value maps the :attr:`winerror` value to

20372

corresponding ``errno.h`` values. This is a subclass of :exc:`OSError`.

20373

20374

.. versionadded:: 2.0

20375

20376

.. versionchanged:: 2.5

20377

- Previous versions put the :cfunc:`GetLastError` codes into :attr:`errno`.

20378

+ Previous versions put the :c:func:`GetLastError` codes into :attr:`errno`.

20379

20380

20381

.. exception:: ZeroDivisionError

20382

diff -r 8527427914a2 Doc/library/fcntl.rst

20383

--- a/Doc/library/fcntl.rst

20384

+++ b/Doc/library/fcntl.rst

20385

@@ -13,7 +13,7 @@

20386

pair: UNIX; I/O control

20387

20388

This module performs file control and I/O control on file descriptors. It is an

20389

-interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.

20390

+interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines.

20391

20392

All functions in this module take a file descriptor *fd* as their first

20393

argument. This can be an integer file descriptor, such as returned by

20394

@@ -31,17 +31,17 @@

20395

:mod:`fcntl` module. The argument *arg* is optional, and defaults to the integer

20396

value ``0``. When present, it can either be an integer value, or a string.

20397

With the argument missing or an integer value, the return value of this function

20398

- is the integer return value of the C :cfunc:`fcntl` call. When the argument is

20399

+ is the integer return value of the C :c:func:`fcntl` call. When the argument is

20400

a string it represents a binary structure, e.g. created by :func:`struct.pack`.

20401

The binary data is copied to a buffer whose address is passed to the C

20402

- :cfunc:`fcntl` call. The return value after a successful call is the contents

20403

+ :c:func:`fcntl` call. The return value after a successful call is the contents

20404

of the buffer, converted to a string object. The length of the returned string

20405

will be the same as the length of the *arg* argument. This is limited to 1024

20406

bytes. If the information returned in the buffer by the operating system is

20407

larger than 1024 bytes, this is most likely to result in a segmentation

20408

violation or a more subtle data corruption.

20409

20410

- If the :cfunc:`fcntl` fails, an :exc:`IOError` is raised.

20411

+ If the :c:func:`fcntl` fails, an :exc:`IOError` is raised.

20412

20413

20414

.. function:: ioctl(fd, op[, arg[, mutate_flag]])

20415

@@ -97,7 +97,7 @@

20416

Perform the lock operation *op* on file descriptor *fd* (file objects providing

20417

a :meth:`fileno` method are accepted as well). See the Unix manual

20418

:manpage:`flock(2)` for details. (On some systems, this function is emulated

20419

- using :cfunc:`fcntl`.)

20420

+ using :c:func:`fcntl`.)

20421

20422

20423

.. function:: lockf(fd, operation, [length, [start, [whence]]])

20424

diff -r 8527427914a2 Doc/library/filecmp.rst

20425

--- a/Doc/library/filecmp.rst

20426

+++ b/Doc/library/filecmp.rst

20427

@@ -1,4 +1,3 @@

20428

-

20429

:mod:`filecmp` --- File and Directory Comparisons

20430

=================================================

20431

20432

@@ -6,16 +5,14 @@

20433

:synopsis: Compare files efficiently.

20434

.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>

20435

20436

+**Source code:** :source:`Lib/filecmp.py`

20437

+

20438

+--------------

20439

20440

The :mod:`filecmp` module defines functions to compare files and directories,

20441

with various optional time/correctness trade-offs. For comparing files,

20442