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#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
229/* replace the unicode encode error with backslash escapes (\N, \x, \u and \U) */
230PyAPI_FUNC(PyObject *) PyCodec_NameReplaceErrors(PyObject *exc);
231#endif
232
233#ifndef Py_LIMITED_API
234PyAPI_DATA(const char *) Py_hexdigits;
235#endif
236
237#ifdef __cplusplus
238}
239#endif
240#endif /* !Py_CODECREGISTRY_H */
241