Skip to content

Commit f65e25b

Browse files
birkenfeldbirkenfeld
committed
Merged revisions 86134,86315-86316,86390,86424-86425,86428,86550,86561-86562,86564-86565,86705,86708,86713 via svnmerge from
svn+ssh://svn.python.org/python/branches/py3k ........ r86134 | georg.brandl | 2010-11-03 08:41:00 +0100 (Mi, 03 Nov 2010) | 1 line A newline in lineno output breaks pyframe output. ........ r86315 | georg.brandl | 2010-11-08 12:05:18 +0100 (Mo, 08 Nov 2010) | 1 line Fix latex conversion glitch in property/feature descriptions. ........ r86316 | georg.brandl | 2010-11-08 12:08:35 +0100 (Mo, 08 Nov 2010) | 1 line Fix typo. ........ r86390 | georg.brandl | 2010-11-10 08:57:10 +0100 (Mi, 10 Nov 2010) | 1 line Fix typo. ........ r86424 | georg.brandl | 2010-11-12 07:19:48 +0100 (Fr, 12 Nov 2010) | 1 line Build a PDF of the FAQs too. ........ r86425 | georg.brandl | 2010-11-12 07:20:12 +0100 (Fr, 12 Nov 2010) | 1 line python#10008: Fix duplicate index entry. ........ r86428 | georg.brandl | 2010-11-12 09:09:26 +0100 (Fr, 12 Nov 2010) | 1 line Fix weird line block in table. ........ r86550 | georg.brandl | 2010-11-20 11:24:34 +0100 (Sa, 20 Nov 2010) | 1 line Fix rst markup errors. ........ r86561 | georg.brandl | 2010-11-20 12:47:10 +0100 (Sa, 20 Nov 2010) | 1 line python#10460: Update indent.pro to match PEP 7 better. ........ r86562 | georg.brandl | 2010-11-20 14:44:41 +0100 (Sa, 20 Nov 2010) | 1 line python#10439: document PyCodec C APIs. ........ r86564 | georg.brandl | 2010-11-20 15:08:53 +0100 (Sa, 20 Nov 2010) | 1 line python#10460: an even better indent.pro. ........ r86565 | georg.brandl | 2010-11-20 15:16:17 +0100 (Sa, 20 Nov 2010) | 1 line socket.gethostbyname(socket.gethostname()) can fail when host name resolution is not set up correctly; do not fail test_socket if this is the case. ........ r86705 | georg.brandl | 2010-11-23 08:54:19 +0100 (Di, 23 Nov 2010) | 1 line python#10468: document Unicode exception creation and access functions. ........ r86708 | georg.brandl | 2010-11-23 09:37:54 +0100 (Di, 23 Nov 2010) | 2 lines python#10511: clarification of what heaps are; suggested by Johannes Hoff. ........ r86713 | georg.brandl | 2010-11-23 19:14:57 +0100 (Di, 23 Nov 2010) | 1 line assert.h is also included. Thanks to Savio Sena. ........
1 parent e553046 commit f65e25b

14 files changed

Lines changed: 292 additions & 71 deletions

File tree

‎Doc/c-api/codec.rst‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
.. _codec-registry:
2+
3+
Codec registry and support functions
4+
====================================
5+
6+
.. cfunction:: int PyCodec_Register(PyObject *search_function)
7+
8+
Register a new codec search function.
9+
10+
As side effect, this tries to load the :mod:`encodings` package, if not yet
11+
done, to make sure that it is always first in the list of search functions.
12+
13+
.. cfunction:: int PyCodec_KnownEncoding(const char *encoding)
14+
15+
Return ``1`` or ``0`` depending on whether there is a registered codec for
16+
the given *encoding*.
17+
18+
.. cfunction:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)
19+
20+
Generic codec based encoding API.
21+
22+
*object* is passed through the encoder function found for the given
23+
*encoding* using the error handling method defined by *errors*. *errors* may
24+
be *NULL* to use the default method defined for the codec. Raises a
25+
:exc:`LookupError` if no encoder can be found.
26+
27+
.. cfunction:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)
28+
29+
Generic codec based decoding API.
30+
31+
*object* is passed through the decoder function found for the given
32+
*encoding* using the error handling method defined by *errors*. *errors* may
33+
be *NULL* to use the default method defined for the codec. Raises a
34+
:exc:`LookupError` if no encoder can be found.
35+
36+
37+
Codec lookup API
38+
----------------
39+
40+
In the following functions, the *encoding* string is looked up converted to all
41+
lower-case characters, which makes encodings looked up through this mechanism
42+
effectively case-insensitive. If no codec is found, a :exc:`KeyError` is set
43+
and *NULL* returned.
44+
45+
.. cfunction:: PyObject* PyCodec_Encoder(const char *encoding)
46+
47+
Get an encoder function for the given *encoding*.
48+
49+
.. cfunction:: PyObject* PyCodec_Decoder(const char *encoding)
50+
51+
Get a decoder function for the given *encoding*.
52+
53+
.. cfunction:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
54+
55+
Get an :class:`IncrementalEncoder` object for the given *encoding*.
56+
57+
.. cfunction:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
58+
59+
Get an :class:`IncrementalDecoder` object for the given *encoding*.
60+
61+
.. cfunction:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
62+
63+
Get a :class:`StreamReader` factory function for the given *encoding*.
64+
65+
.. cfunction:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
66+
67+
Get a :class:`StreamWriter` factory function for the given *encoding*.
68+
69+
70+
Registry API for Unicode encoding error handlers
71+
------------------------------------------------
72+
73+
.. cfunction:: int PyCodec_RegisterError(const char *name, PyObject *error)
74+
75+
Register the error handling callback function *error* under the given *name*.
76+
This callback function will be called by a codec when it encounters
77+
unencodable characters/undecodable bytes and *name* is specified as the error
78+
parameter in the call to the encode/decode function.
79+
80+
The callback gets a single argument, an instance of
81+
:exc:`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or
82+
:exc:`UnicodeTranslateError` that holds information about the problematic
83+
sequence of characters or bytes and their offset in the original string (see
84+
:ref:`unicodeexceptions` for functions to extract this information). The
85+
callback must either raise the given exception, or return a two-item tuple
86+
containing the replacement for the problematic sequence, and an integer
87+
giving the offset in the original string at which encoding/decoding should be
88+
resumed.
89+
90+
Return ``0`` on success, ``-1`` on error.
91+
92+
.. cfunction:: PyObject* PyCodec_LookupError(const char *name)
93+
94+
Lookup the error handling callback function registered under *name*. As a
95+
special case *NULL* can be passed, in which case the error handling callback
96+
for "strict" will be returned.
97+
98+
.. cfunction:: PyObject* PyCodec_StrictErrors(PyObject *exc)
99+
100+
Raise *exc* as an exception.
101+
102+
.. cfunction:: PyObject* PyCodec_IgnoreErrors(PyObject *exc)
103+
104+
Ignore the unicode error, skipping the faulty input.
105+
106+
.. cfunction:: PyObject* PyCodec_ReplaceErrors(PyObject *exc)
107+
108+
Replace the unicode encode error with ``?`` or ``U+FFFD``.
109+
110+
.. cfunction:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)
111+
112+
Replace the unicode encode error with XML character references.
113+
114+
.. cfunction:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)
115+
116+
Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and
117+
``\U``).
118+

‎Doc/c-api/exceptions.rst‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -446,6 +446,83 @@ Exception Objects
446446
This steals a reference to *ctx*.
447447

448448

449+
.. _unicodeexceptions:
450+
451+
Unicode Exception Objects
452+
=========================
453+
454+
The following functions are used to create and modify Unicode exceptions from C.
455+
456+
.. 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)
457+
458+
Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
459+
*object*, *length*, *start*, *end* and *reason*.
460+
461+
.. 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)
462+
463+
Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
464+
*object*, *length*, *start*, *end* and *reason*.
465+
466+
.. cfunction:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
467+
468+
Create a :class:`UnicodeTranslateError` object with the attributes *object*,
469+
*length*, *start*, *end* and *reason*.
470+
471+
.. cfunction:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
472+
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
473+
474+
Return the *encoding* attribute of the given exception object.
475+
476+
.. cfunction:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
477+
PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
478+
PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
479+
480+
Return the *object* attribute of the given exception object.
481+
482+
.. cfunction:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
483+
int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
484+
int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
485+
486+
Get the *start* attribute of the given exception object and place it into
487+
*\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on
488+
failure.
489+
490+
.. cfunction:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
491+
int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
492+
int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
493+
494+
Set the *start* attribute of the given exception object to *start*. Return
495+
``0`` on success, ``-1`` on failure.
496+
497+
.. cfunction:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
498+
int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
499+
int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
500+
501+
Get the *end* attribute of the given exception object and place it into
502+
*\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on
503+
failure.
504+
505+
.. cfunction:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
506+
int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
507+
int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
508+
509+
Set the *end* attribute of the given exception object to *end*. Return ``0``
510+
on success, ``-1`` on failure.
511+
512+
.. cfunction:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
513+
PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
514+
PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
515+
516+
Return the *reason* attribute of the given exception object.
517+
518+
.. cfunction:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
519+
int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
520+
int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
521+
522+
Set the *reason* attribute of the given exception object to *reason*. Return
523+
``0`` on success, ``-1`` on failure.
524+
525+
449526
Recursion Control
450527
=================
451528

‎Doc/c-api/intro.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ included in your code by the following line::
4141
#include "Python.h"
4242

4343
This implies inclusion of the following standard headers: ``<stdio.h>``,
44-
``<string.h>``, ``<errno.h>``, ``<limits.h>``, and ``<stdlib.h>`` (if
45-
available).
44+
``<string.h>``, ``<errno.h>``, ``<limits.h>``, ``<assert.h>`` and ``<stdlib.h>``
45+
(if available).
4646

4747
.. note::
4848

‎Doc/c-api/utilities.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,4 @@ and parsing function arguments and constructing Python values from C values.
1818
arg.rst
1919
conversion.rst
2020
reflection.rst
21+
codec.rst

‎Doc/conf.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,8 @@
129129
'Python Tutorial', _stdauthor, 'manual'),
130130
('using/index', 'using.tex',
131131
'Python Setup and Usage', _stdauthor, 'manual'),
132+
('faq/index', 'faq.tex',
133+
'Python Frequently Asked Questions', _stdauthor, 'manual'),
132134
('whatsnew/' + version, 'whatsnew.tex',
133135
'What\'s New in Python', 'A. M. Kuchling', 'howto'),
134136
]

‎Doc/library/heapq.rst‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,12 @@
1111
This module provides an implementation of the heap queue algorithm, also known
1212
as the priority queue algorithm.
1313

14-
Heaps are arrays for which ``heap[k] <= heap[2*k+1]`` and ``heap[k] <=
15-
heap[2*k+2]`` for all *k*, counting elements from zero. For the sake of
16-
comparison, non-existing elements are considered to be infinite. The
17-
interesting property of a heap is that ``heap[0]`` is always its smallest
18-
element.
14+
Heaps are binary trees for which every parent node has a value less than or
15+
equal to any of its children. This implementation uses arrays for which
16+
``heap[k] <= heap[2*k+1]`` and ``heap[k] <= heap[2*k+2]`` for all *k*, counting
17+
elements from zero. For the sake of comparison, non-existing elements are
18+
considered to be infinite. The interesting property of a heap is that its
19+
smallest element is always the root, ``heap[0]``.
1920

2021
The API below differs from textbook heap algorithms in two aspects: (a) We use
2122
zero-based indexing. This makes the relationship between the index for a node

‎Doc/library/itertools.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,6 @@ Iterator Arguments Resu
6767
:func:`permutations` p[, r] r-length tuples, all possible orderings, no repeated elements
6868
:func:`combinations` p, r r-length tuples, in sorted order, no repeated elements
6969
:func:`combinations_with_replacement` p, r r-length tuples, in sorted order, with repeated elements
70-
|
7170
``product('ABCD', repeat=2)`` ``AA AB AC AD BA BB BC BD CA CB CC CD DA DB DC DD``
7271
``permutations('ABCD', 2)`` ``AB AC AD BA BC BD CA CB CD DA DB DC``
7372
``combinations('ABCD', 2)`` ``AB AC AD BC BD CD``

‎Doc/library/xml.sax.handler.rst‎

Lines changed: 51 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -49,52 +49,57 @@ for the feature and property names.
4949

5050
.. data:: feature_namespaces
5151

52-
Value: ``"http://xml.org/sax/features/namespaces"`` --- true: Perform Namespace
53-
processing. --- false: Optionally do not perform Namespace processing (implies
54-
namespace-prefixes; default). --- access: (parsing) read-only; (not parsing)
55-
read/write
52+
| value: ``"http://xml.org/sax/features/namespaces"``
53+
| true: Perform Namespace processing.
54+
| false: Optionally do not perform Namespace processing (implies
55+
namespace-prefixes; default).
56+
| access: (parsing) read-only; (not parsing) read/write
5657
5758

5859
.. data:: feature_namespace_prefixes
5960

60-
Value: ``"http://xml.org/sax/features/namespace-prefixes"`` --- true: Report
61-
the original prefixed names and attributes used for Namespace
62-
declarations. --- false: Do not report attributes used for Namespace
63-
declarations, and optionally do not report original prefixed names
64-
(default). --- access: (parsing) read-only; (not parsing) read/write
61+
| value: ``"http://xml.org/sax/features/namespace-prefixes"``
62+
| true: Report the original prefixed names and attributes used for Namespace
63+
declarations.
64+
| false: Do not report attributes used for Namespace declarations, and
65+
optionally do not report original prefixed names (default).
66+
| access: (parsing) read-only; (not parsing) read/write
6567
6668

6769
.. data:: feature_string_interning
6870

69-
Value: ``"http://xml.org/sax/features/string-interning"`` --- true: All element
70-
names, prefixes, attribute names, Namespace URIs, and local names are interned
71-
using the built-in intern function. --- false: Names are not necessarily
72-
interned, although they may be (default). --- access: (parsing) read-only; (not
73-
parsing) read/write
71+
| value: ``"http://xml.org/sax/features/string-interning"``
72+
| true: All element names, prefixes, attribute names, Namespace URIs, and
73+
local names are interned using the built-in intern function.
74+
| false: Names are not necessarily interned, although they may be (default).
75+
| access: (parsing) read-only; (not parsing) read/write
7476
7577

7678
.. data:: feature_validation
7779

78-
Value: ``"http://xml.org/sax/features/validation"`` --- true: Report all
79-
validation errors (implies external-general-entities and
80-
external-parameter-entities). --- false: Do not report validation errors. ---
81-
access: (parsing) read-only; (not parsing) read/write
80+
| value: ``"http://xml.org/sax/features/validation"``
81+
| true: Report all validation errors (implies external-general-entities and
82+
external-parameter-entities).
83+
| false: Do not report validation errors.
84+
| access: (parsing) read-only; (not parsing) read/write
8285
8386

8487
.. data:: feature_external_ges
8588

86-
Value: ``"http://xml.org/sax/features/external-general-entities"`` --- true:
87-
Include all external general (text) entities. --- false: Do not include
88-
external general entities. --- access: (parsing) read-only; (not parsing)
89-
read/write
89+
| value: ``"http://xml.org/sax/features/external-general-entities"``
90+
| true: Include all external general (text) entities.
91+
| false: Do not include external general entities.
92+
| access: (parsing) read-only; (not parsing) read/write
9093
9194

9295
.. data:: feature_external_pes
9396

94-
Value: ``"http://xml.org/sax/features/external-parameter-entities"`` --- true:
95-
Include all external parameter entities, including the external DTD subset. ---
96-
false: Do not include any external parameter entities, even the external DTD
97-
subset. --- access: (parsing) read-only; (not parsing) read/write
97+
| value: ``"http://xml.org/sax/features/external-parameter-entities"``
98+
| true: Include all external parameter entities, including the external DTD
99+
subset.
100+
| false: Do not include any external parameter entities, even the external
101+
DTD subset.
102+
| access: (parsing) read-only; (not parsing) read/write
98103
99104

100105
.. data:: all_features
@@ -104,34 +109,38 @@ for the feature and property names.
104109

105110
.. data:: property_lexical_handler
106111

107-
Value: ``"http://xml.org/sax/properties/lexical-handler"`` --- data type:
108-
xml.sax.sax2lib.LexicalHandler (not supported in Python 2) --- description: An
109-
optional extension handler for lexical events like comments. --- access:
110-
read/write
112+
| value: ``"http://xml.org/sax/properties/lexical-handler"``
113+
| data type: xml.sax.sax2lib.LexicalHandler (not supported in Python 2)
114+
| description: An optional extension handler for lexical events like
115+
comments.
116+
| access: read/write
111117
112118

113119
.. data:: property_declaration_handler
114120

115-
Value: ``"http://xml.org/sax/properties/declaration-handler"`` --- data type:
116-
xml.sax.sax2lib.DeclHandler (not supported in Python 2) --- description: An
117-
optional extension handler for DTD-related events other than notations and
118-
unparsed entities. --- access: read/write
121+
| value: ``"http://xml.org/sax/properties/declaration-handler"``
122+
| data type: xml.sax.sax2lib.DeclHandler (not supported in Python 2)
123+
| description: An optional extension handler for DTD-related events other
124+
than notations and unparsed entities.
125+
| access: read/write
119126
120127

121128
.. data:: property_dom_node
122129

123-
Value: ``"http://xml.org/sax/properties/dom-node"`` --- data type:
124-
org.w3c.dom.Node (not supported in Python 2) --- description: When parsing,
125-
the current DOM node being visited if this is a DOM iterator; when not parsing,
126-
the root DOM node for iteration. --- access: (parsing) read-only; (not parsing)
127-
read/write
130+
| value: ``"http://xml.org/sax/properties/dom-node"``
131+
| data type: org.w3c.dom.Node (not supported in Python 2)
132+
| description: When parsing, the current DOM node being visited if this is
133+
a DOM iterator; when not parsing, the root DOM node for iteration.
134+
| access: (parsing) read-only; (not parsing) read/write
128135
129136

130137
.. data:: property_xml_string
131138

132-
Value: ``"http://xml.org/sax/properties/xml-string"`` --- data type: String ---
133-
description: The literal string of characters that was the source for the
134-
current event. --- access: read-only
139+
| value: ``"http://xml.org/sax/properties/xml-string"``
140+
| data type: String
141+
| description: The literal string of characters that was the source for the
142+
current event.
143+
| access: read-only
135144
136145

137146
.. data:: all_properties

0 commit comments

Comments
 (0)