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 registry 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
48#ifndef Py_LIMITED_API
49PyAPI_FUNC(PyObject *) _PyCodec_Lookup(
50 const char *encoding
51 );
52
53PyAPI_FUNC(int) _PyCodec_Forget(
54 const char *encoding
55 );
56#endif
57
58/* Codec registry encoding check API.
59
60 Returns 1/0 depending on whether there is a registered codec for
61 the given encoding.
62
63*/
64
65PyAPI_FUNC(int) PyCodec_KnownEncoding(
66 const char *encoding
67 );
68
69/* Generic codec based encoding API.
70
71 object is passed through the encoder function found for the given
72 encoding using the error handling method defined by errors. errors
73 may be NULL to use the default method defined for the codec.
74
75 Raises a LookupError in case no encoder can be found.
76
77 */
78
79PyAPI_FUNC(PyObject *) PyCodec_Encode(
80 PyObject *object,
81 const char *encoding,
82 const char *errors
83 );
84
85/* Generic codec based decoding API.
86
87 object is passed through the decoder function found for the given
88 encoding using the error handling method defined by errors. errors
89 may be NULL to use the default method defined for the codec.
90
91 Raises a LookupError in case no encoder can be found.
92
93 */
94
95PyAPI_FUNC(PyObject *) PyCodec_Decode(
96 PyObject *object,
97 const char *encoding,
98 const char *errors
99 );
100
101#ifndef Py_LIMITED_API
102/* Text codec specific encoding and decoding API.
103
104 Checks the encoding against a list of codecs which do not
105 implement a str<->bytes encoding before attempting the
106 operation.
107
108 Please note that these APIs are internal and should not
109 be used in Python C extensions.
110
111 XXX (ncoghlan): should we make these, or something like them, public
112 in Python 3.5+?
113
114 */
115PyAPI_FUNC(PyObject *) _PyCodec_LookupTextEncoding(
116 const char *encoding,
117 const char *alternate_command
118 );
119
120PyAPI_FUNC(PyObject *) _PyCodec_EncodeText(
121 PyObject *object,
122 const char *encoding,
123 const char *errors
124 );
125
126PyAPI_FUNC(PyObject *) _PyCodec_DecodeText(
127 PyObject *object,
128 const char *encoding,
129 const char *errors
130 );
131
132/* These two aren't actually text encoding specific, but _io.TextIOWrapper
133 * is the only current API consumer.
134 */
135PyAPI_FUNC(PyObject *) _PyCodecInfo_GetIncrementalDecoder(
136 PyObject *codec_info,
137 const char *errors
138 );
139
140PyAPI_FUNC(PyObject *) _PyCodecInfo_GetIncrementalEncoder(
141 PyObject *codec_info,
142 const char *errors
143 );
144#endif
145
146
147
148/* --- Codec Lookup APIs --------------------------------------------------
149
150 All APIs return a codec object with incremented refcount and are
151 based on _PyCodec_Lookup(). The same comments w/r to the encoding
152 name also apply to these APIs.
153
154*/
155
156/* Get an encoder function for the given encoding. */
157
158PyAPI_FUNC(PyObject *) PyCodec_Encoder(
159 const char *encoding
160 );
161
162/* Get a decoder function for the given encoding. */
163
164PyAPI_FUNC(PyObject *) PyCodec_Decoder(
165 const char *encoding
166 );
167
168/* Get an IncrementalEncoder object for the given encoding. */
169
170PyAPI_FUNC(PyObject *) PyCodec_IncrementalEncoder(
171 const char *encoding,
172 const char *errors
173 );
174
175/* Get an IncrementalDecoder object function for the given encoding. */
176
177PyAPI_FUNC(PyObject *) PyCodec_IncrementalDecoder(
178 const char *encoding,
179 const char *errors
180 );
181
182/* Get a StreamReader factory function for the given encoding. */
183
184PyAPI_FUNC(PyObject *) PyCodec_StreamReader(
185 const char *encoding,
186 PyObject *stream,
187 const char *errors
188 );
189
190/* Get a StreamWriter factory function for the given encoding. */
191
192PyAPI_FUNC(PyObject *) PyCodec_StreamWriter(
193 const char *encoding,
194 PyObject *stream,
195 const char *errors
196 );
197
198/* Unicode encoding error handling callback registry API */
199
200/* Register the error handling callback function error under the given
201 name. This function will be called by the codec when it encounters
202 unencodable characters/undecodable bytes and doesn't know the
203 callback name, when name is specified as the error parameter
204 in the call to the encode/decode function.
205 Return 0 on success, -1 on error */
206PyAPI_FUNC(int) PyCodec_RegisterError(const char *name, PyObject *error);
207
208/* Lookup the error handling callback function registered under the given
209 name. As a special case NULL can be passed, in which case
210 the error handling callback for "strict" will be returned. */
211PyAPI_FUNC(PyObject *) PyCodec_LookupError(const char *name);
212
213/* raise exc as an exception */
214PyAPI_FUNC(PyObject *) PyCodec_StrictErrors(PyObject *exc);
215
216/* ignore the unicode error, skipping the faulty input */
217PyAPI_FUNC(PyObject *) PyCodec_IgnoreErrors(PyObject *exc);
218
219/* replace the unicode encode error with ? or U+FFFD */
220PyAPI_FUNC(PyObject *) PyCodec_ReplaceErrors(PyObject *exc);
221
222/* replace the unicode encode error with XML character references */
223PyAPI_FUNC(PyObject *) PyCodec_XMLCharRefReplaceErrors(PyObject *exc);
224
225/* replace the unicode encode error with backslash escapes (\x, \u and \U) */
226PyAPI_FUNC(PyObject *) PyCodec_BackslashReplaceErrors(PyObject *exc);
227
228/* replace the unicode encode error with backslash escapes (\N, \x, \u and \U) */
229PyAPI_FUNC(PyObject *) PyCodec_NameReplaceErrors(PyObject *exc);
230
231PyAPI_DATA(const char *) Py_hexdigits;
232
233#ifdef __cplusplus
234}
235#endif
236#endif /* !Py_CODECREGISTRY_H */
237