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