1#ifndef Py_CODECREGISTRY_H
2#define Py_CODECREGISTRY_H
3#ifdef __cplusplus
4extern "C" {
5#endif
6
7/* ------------------------------------------------------------------------
8
9 Python Codec Registry and support functions
10
11
12Written by Marc-Andre Lemburg (mal@lemburg.com).
13
14Copyright (c) Corporation for National Research Initiatives.
15
16 ------------------------------------------------------------------------ */
17
18/* Register a new codec search function.
19
20 As side effect, this tries to load the encodings package, if not
21 yet done, to make sure that it is always first in the list of
22 search functions.
23
24 The search_function's refcount is incremented by this function. */
25
26PyAPI_FUNC(int) PyCodec_Register(
27 PyObject *search_function
28 );
29
30/* Codec register lookup API.
31
32 Looks up the given encoding and returns a CodecInfo object with
33 function attributes which implement the different aspects of
34 processing the encoding.
35
36 The encoding string is looked up converted to all lower-case
37 characters. This makes encodings looked up through this mechanism
38 effectively case-insensitive.
39
40 If no codec is found, a KeyError is set and NULL returned.
41
42 As side effect, this tries to load the encodings package, if not
43 yet done. This is part of the lazy load strategy for the encodings
44 package.
45
46 */
47
48PyAPI_FUNC(PyObject *) _PyCodec_Lookup(
49 const char *encoding
50 );
51
52/* Generic codec based encoding API.
53
54 object is passed through the encoder function found for the given
55 encoding using the error handling method defined by errors. errors
56 may be NULL to use the default method defined for the codec.
57
58 Raises a LookupError in case no encoder can be found.
59
60 */
61
62PyAPI_FUNC(PyObject *) PyCodec_Encode(
63 PyObject *object,
64 const char *encoding,
65 const char *errors
66 );
67
68/* Generic codec based decoding API.
69
70 object is passed through the decoder function found for the given
71 encoding using the error handling method defined by errors. errors
72 may be NULL to use the default method defined for the codec.
73
74 Raises a LookupError in case no encoder can be found.
75
76 */
77
78PyAPI_FUNC(PyObject *) PyCodec_Decode(
79 PyObject *object,
80 const char *encoding,
81 const char *errors
82 );
83
84/* Text codec specific encoding and decoding API.
85
86 Checks the encoding against a list of codecs which do not
87 implement a unicode<->bytes encoding before attempting the
88 operation.
89
90 Please note that these APIs are internal and should not
91 be used in Python C extensions.
92
93 XXX (ncoghlan): should we make these, or something like them, public
94 in Python 3.5+?
95
96 */
97PyAPI_FUNC(PyObject *) _PyCodec_LookupTextEncoding(
98 const char *encoding,
99 const char *alternate_command
100 );
101
102PyAPI_FUNC(PyObject *) _PyCodec_EncodeText(
103 PyObject *object,
104 const char *encoding,
105 const char *errors
106 );
107
108PyAPI_FUNC(PyObject *) _PyCodec_DecodeText(
109 PyObject *object,
110 const char *encoding,
111 const char *errors
112 );
113
114/* These two aren't actually text encoding specific, but _io.TextIOWrapper
115 * is the only current API consumer.
116 */
117PyAPI_FUNC(PyObject *) _PyCodecInfo_GetIncrementalDecoder(
118 PyObject *codec_info,
119 const char *errors
120 );
121
122PyAPI_FUNC(PyObject *) _PyCodecInfo_GetIncrementalEncoder(
123 PyObject *codec_info,
124 const char *errors
125 );
126
127
128
129/* --- Codec Lookup APIs --------------------------------------------------
130
131 All APIs return a codec object with incremented refcount and are
132 based on _PyCodec_Lookup(). The same comments w/r to the encoding
133 name also apply to these APIs.
134
135*/
136
137/* Get an encoder function for the given encoding. */
138
139PyAPI_FUNC(PyObject *) PyCodec_Encoder(
140 const char *encoding
141 );
142
143/* Get a decoder function for the given encoding. */
144
145PyAPI_FUNC(PyObject *) PyCodec_Decoder(
146 const char *encoding
147 );
148
149/* Get an IncrementalEncoder object for the given encoding. */
150
151PyAPI_FUNC(PyObject *) PyCodec_IncrementalEncoder(
152 const char *encoding,
153 const char *errors
154 );
155
156/* Get an IncrementalDecoder object function for the given encoding. */
157
158PyAPI_FUNC(PyObject *) PyCodec_IncrementalDecoder(
159 const char *encoding,
160 const char *errors
161 );
162
163/* Get a StreamReader factory function for the given encoding. */
164
165PyAPI_FUNC(PyObject *) PyCodec_StreamReader(
166 const char *encoding,
167 PyObject *stream,
168 const char *errors
169 );
170
171/* Get a StreamWriter factory function for the given encoding. */
172
173PyAPI_FUNC(PyObject *) PyCodec_StreamWriter(
174 const char *encoding,
175 PyObject *stream,
176 const char *errors
177 );
178
179/* Unicode encoding error handling callback registry API */
180
181/* Register the error handling callback function error under the given
182 name. This function will be called by the codec when it encounters
183 unencodable characters/undecodable bytes and doesn't know the
184 callback name, when name is specified as the error parameter
185 in the call to the encode/decode function.
186 Return 0 on success, -1 on error */
187PyAPI_FUNC(int) PyCodec_RegisterError(const char *name, PyObject *error);
188
189/* Lookup the error handling callback function registered under the given
190 name. As a special case NULL can be passed, in which case
191 the error handling callback for "strict" will be returned. */
192PyAPI_FUNC(PyObject *) PyCodec_LookupError(const char *name);
193
194/* raise exc as an exception */
195PyAPI_FUNC(PyObject *) PyCodec_StrictErrors(PyObject *exc);
196
197/* ignore the unicode error, skipping the faulty input */
198PyAPI_FUNC(PyObject *) PyCodec_IgnoreErrors(PyObject *exc);
199
200/* replace the unicode encode error with ? or U+FFFD */
201PyAPI_FUNC(PyObject *) PyCodec_ReplaceErrors(PyObject *exc);
202
203/* replace the unicode encode error with XML character references */
204PyAPI_FUNC(PyObject *) PyCodec_XMLCharRefReplaceErrors(PyObject *exc);
205
206/* replace the unicode encode error with backslash escapes (\x, \u and \U) */
207PyAPI_FUNC(PyObject *) PyCodec_BackslashReplaceErrors(PyObject *exc);
208
209#ifdef __cplusplus
210}
211#endif
212#endif /* !Py_CODECREGISTRY_H */
213