blob: 4ea934e861d612cdbfc47c7c09d7de9936bae8bb [file] [log] [blame]
Guido van Rossum30944842000-03-10 22:32:23 +00001#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
Guido van Rossum16b1ad92000-08-03 16:24:25 +000014Copyright (c) Corporation for National Research Initiatives.
Guido van Rossum30944842000-03-10 22:32:23 +000015
16 ------------------------------------------------------------------------ */
17
Fred Drake3ac3edc2000-05-09 19:51:10 +000018/* 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
Mark Hammond91a681d2002-08-12 07:21:58 +000026PyAPI_FUNC(int) PyCodec_Register(
Guido van Rossum30944842000-03-10 22:32:23 +000027 PyObject *search_function
28 );
29
Marc-André Lemburgb2750b52008-06-06 12:18:17 +000030/* Codec registry lookup API.
Fred Drake3ac3edc2000-05-09 19:51:10 +000031
Thomas Woutersa9773292006-04-21 09:43:23 +000032 Looks up the given encoding and returns a CodecInfo object with
33 function attributes which implement the different aspects of
34 processing the encoding.
Fred Drake3ac3edc2000-05-09 19:51:10 +000035
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
Thomas Woutersa9773292006-04-21 09:43:23 +000040 If no codec is found, a KeyError is set and NULL returned.
Fred Drake3ac3edc2000-05-09 19:51:10 +000041
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
Mark Hammond91a681d2002-08-12 07:21:58 +000048PyAPI_FUNC(PyObject *) _PyCodec_Lookup(
Guido van Rossum30944842000-03-10 22:32:23 +000049 const char *encoding
50 );
51
Marc-André Lemburgb2750b52008-06-06 12:18:17 +000052/* Codec registry encoding check API.
53
54 Returns 1/0 depending on whether there is a registered codec for
55 the given encoding.
56
57*/
58
59PyAPI_FUNC(int) PyCodec_KnownEncoding(
60 const char *encoding
61 );
62
Fred Drake3ac3edc2000-05-09 19:51:10 +000063/* Generic codec based encoding API.
Guido van Rossum30944842000-03-10 22:32:23 +000064
Fred Drake3ac3edc2000-05-09 19:51:10 +000065 object is passed through the encoder function found for the given
66 encoding using the error handling method defined by errors. errors
67 may be NULL to use the default method defined for the codec.
68
69 Raises a LookupError in case no encoder can be found.
Guido van Rossum30944842000-03-10 22:32:23 +000070
Fred Drake3ac3edc2000-05-09 19:51:10 +000071 */
Guido van Rossum30944842000-03-10 22:32:23 +000072
Mark Hammond91a681d2002-08-12 07:21:58 +000073PyAPI_FUNC(PyObject *) PyCodec_Encode(
Guido van Rossum30944842000-03-10 22:32:23 +000074 PyObject *object,
75 const char *encoding,
76 const char *errors
77 );
78
Fred Drake3ac3edc2000-05-09 19:51:10 +000079/* Generic codec based decoding API.
80
81 object is passed through the decoder function found for the given
82 encoding using the error handling method defined by errors. errors
83 may be NULL to use the default method defined for the codec.
84
85 Raises a LookupError in case no encoder can be found.
86
87 */
88
Mark Hammond91a681d2002-08-12 07:21:58 +000089PyAPI_FUNC(PyObject *) PyCodec_Decode(
Guido van Rossum30944842000-03-10 22:32:23 +000090 PyObject *object,
91 const char *encoding,
92 const char *errors
93 );
94
Fred Drake3ac3edc2000-05-09 19:51:10 +000095/* --- Codec Lookup APIs --------------------------------------------------
96
97 All APIs return a codec object with incremented refcount and are
98 based on _PyCodec_Lookup(). The same comments w/r to the encoding
99 name also apply to these APIs.
100
101*/
102
103/* Get an encoder function for the given encoding. */
104
Mark Hammond91a681d2002-08-12 07:21:58 +0000105PyAPI_FUNC(PyObject *) PyCodec_Encoder(
Fred Drake3ac3edc2000-05-09 19:51:10 +0000106 const char *encoding
107 );
108
109/* Get a decoder function for the given encoding. */
110
Mark Hammond91a681d2002-08-12 07:21:58 +0000111PyAPI_FUNC(PyObject *) PyCodec_Decoder(
Fred Drake3ac3edc2000-05-09 19:51:10 +0000112 const char *encoding
113 );
114
Thomas Woutersa9773292006-04-21 09:43:23 +0000115/* Get a IncrementalEncoder object for the given encoding. */
116
117PyAPI_FUNC(PyObject *) PyCodec_IncrementalEncoder(
118 const char *encoding,
119 const char *errors
120 );
121
122/* Get a IncrementalDecoder object function for the given encoding. */
123
124PyAPI_FUNC(PyObject *) PyCodec_IncrementalDecoder(
125 const char *encoding,
126 const char *errors
127 );
128
Fred Drake3ac3edc2000-05-09 19:51:10 +0000129/* Get a StreamReader factory function for the given encoding. */
130
Mark Hammond91a681d2002-08-12 07:21:58 +0000131PyAPI_FUNC(PyObject *) PyCodec_StreamReader(
Fred Drake3ac3edc2000-05-09 19:51:10 +0000132 const char *encoding,
133 PyObject *stream,
134 const char *errors
135 );
136
137/* Get a StreamWriter factory function for the given encoding. */
138
Mark Hammond91a681d2002-08-12 07:21:58 +0000139PyAPI_FUNC(PyObject *) PyCodec_StreamWriter(
Fred Drake3ac3edc2000-05-09 19:51:10 +0000140 const char *encoding,
141 PyObject *stream,
142 const char *errors
143 );
144
Walter Dörwald3aeb6322002-09-02 13:14:32 +0000145/* Unicode encoding error handling callback registry API */
146
Georg Brandlf65e25b2010-11-26 09:05:43 +0000147/* Register the error handling callback function error under the given
Walter Dörwald3aeb6322002-09-02 13:14:32 +0000148 name. This function will be called by the codec when it encounters
149 unencodable characters/undecodable bytes and doesn't know the
150 callback name, when name is specified as the error parameter
151 in the call to the encode/decode function.
152 Return 0 on success, -1 on error */
153PyAPI_FUNC(int) PyCodec_RegisterError(const char *name, PyObject *error);
154
Georg Brandlf65e25b2010-11-26 09:05:43 +0000155/* Lookup the error handling callback function registered under the given
156 name. As a special case NULL can be passed, in which case
Walter Dörwald3aeb6322002-09-02 13:14:32 +0000157 the error handling callback for "strict" will be returned. */
158PyAPI_FUNC(PyObject *) PyCodec_LookupError(const char *name);
159
160/* raise exc as an exception */
161PyAPI_FUNC(PyObject *) PyCodec_StrictErrors(PyObject *exc);
162
163/* ignore the unicode error, skipping the faulty input */
164PyAPI_FUNC(PyObject *) PyCodec_IgnoreErrors(PyObject *exc);
165
Georg Brandlf65e25b2010-11-26 09:05:43 +0000166/* replace the unicode encode error with ? or U+FFFD */
Walter Dörwald3aeb6322002-09-02 13:14:32 +0000167PyAPI_FUNC(PyObject *) PyCodec_ReplaceErrors(PyObject *exc);
168
169/* replace the unicode encode error with XML character references */
170PyAPI_FUNC(PyObject *) PyCodec_XMLCharRefReplaceErrors(PyObject *exc);
171
172/* replace the unicode encode error with backslash escapes (\x, \u and \U) */
173PyAPI_FUNC(PyObject *) PyCodec_BackslashReplaceErrors(PyObject *exc);
174
Guido van Rossum30944842000-03-10 22:32:23 +0000175#ifdef __cplusplus
176}
177#endif
178#endif /* !Py_CODECREGISTRY_H */