blob: 0d76241dbf593c468b96db81a31f59c68c562510 [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
Fred Drake3ac3edc2000-05-09 19:51:10 +000030/* Codec register lookup API.
31
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
Fred Drake3ac3edc2000-05-09 19:51:10 +000052/* Generic codec based encoding API.
Guido van Rossum30944842000-03-10 22:32:23 +000053
Fred Drake3ac3edc2000-05-09 19:51:10 +000054 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.
Guido van Rossum30944842000-03-10 22:32:23 +000059
Fred Drake3ac3edc2000-05-09 19:51:10 +000060 */
Guido van Rossum30944842000-03-10 22:32:23 +000061
Mark Hammond91a681d2002-08-12 07:21:58 +000062PyAPI_FUNC(PyObject *) PyCodec_Encode(
Guido van Rossum30944842000-03-10 22:32:23 +000063 PyObject *object,
64 const char *encoding,
65 const char *errors
66 );
67
Fred Drake3ac3edc2000-05-09 19:51:10 +000068/* 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
Mark Hammond91a681d2002-08-12 07:21:58 +000078PyAPI_FUNC(PyObject *) PyCodec_Decode(
Guido van Rossum30944842000-03-10 22:32:23 +000079 PyObject *object,
80 const char *encoding,
81 const char *errors
82 );
83
Fred Drake3ac3edc2000-05-09 19:51:10 +000084/* --- Codec Lookup APIs --------------------------------------------------
85
86 All APIs return a codec object with incremented refcount and are
87 based on _PyCodec_Lookup(). The same comments w/r to the encoding
88 name also apply to these APIs.
89
90*/
91
92/* Get an encoder function for the given encoding. */
93
Mark Hammond91a681d2002-08-12 07:21:58 +000094PyAPI_FUNC(PyObject *) PyCodec_Encoder(
Fred Drake3ac3edc2000-05-09 19:51:10 +000095 const char *encoding
96 );
97
98/* Get a decoder function for the given encoding. */
99
Mark Hammond91a681d2002-08-12 07:21:58 +0000100PyAPI_FUNC(PyObject *) PyCodec_Decoder(
Fred Drake3ac3edc2000-05-09 19:51:10 +0000101 const char *encoding
102 );
103
Thomas Woutersa9773292006-04-21 09:43:23 +0000104/* Get a IncrementalEncoder object for the given encoding. */
105
106PyAPI_FUNC(PyObject *) PyCodec_IncrementalEncoder(
107 const char *encoding,
108 const char *errors
109 );
110
111/* Get a IncrementalDecoder object function for the given encoding. */
112
113PyAPI_FUNC(PyObject *) PyCodec_IncrementalDecoder(
114 const char *encoding,
115 const char *errors
116 );
117
Fred Drake3ac3edc2000-05-09 19:51:10 +0000118/* Get a StreamReader factory function for the given encoding. */
119
Mark Hammond91a681d2002-08-12 07:21:58 +0000120PyAPI_FUNC(PyObject *) PyCodec_StreamReader(
Fred Drake3ac3edc2000-05-09 19:51:10 +0000121 const char *encoding,
122 PyObject *stream,
123 const char *errors
124 );
125
126/* Get a StreamWriter factory function for the given encoding. */
127
Mark Hammond91a681d2002-08-12 07:21:58 +0000128PyAPI_FUNC(PyObject *) PyCodec_StreamWriter(
Fred Drake3ac3edc2000-05-09 19:51:10 +0000129 const char *encoding,
130 PyObject *stream,
131 const char *errors
132 );
133
Walter Dörwald3aeb6322002-09-02 13:14:32 +0000134/* Unicode encoding error handling callback registry API */
135
136/* Register the error handling callback function error under the name
137 name. This function will be called by the codec when it encounters
138 unencodable characters/undecodable bytes and doesn't know the
139 callback name, when name is specified as the error parameter
140 in the call to the encode/decode function.
141 Return 0 on success, -1 on error */
142PyAPI_FUNC(int) PyCodec_RegisterError(const char *name, PyObject *error);
143
144/* Lookup the error handling callback function registered under the
145 name error. As a special case NULL can be passed, in which case
146 the error handling callback for "strict" will be returned. */
147PyAPI_FUNC(PyObject *) PyCodec_LookupError(const char *name);
148
149/* raise exc as an exception */
150PyAPI_FUNC(PyObject *) PyCodec_StrictErrors(PyObject *exc);
151
152/* ignore the unicode error, skipping the faulty input */
153PyAPI_FUNC(PyObject *) PyCodec_IgnoreErrors(PyObject *exc);
154
155/* replace the unicode error with ? or U+FFFD */
156PyAPI_FUNC(PyObject *) PyCodec_ReplaceErrors(PyObject *exc);
157
158/* replace the unicode encode error with XML character references */
159PyAPI_FUNC(PyObject *) PyCodec_XMLCharRefReplaceErrors(PyObject *exc);
160
161/* replace the unicode encode error with backslash escapes (\x, \u and \U) */
162PyAPI_FUNC(PyObject *) PyCodec_BackslashReplaceErrors(PyObject *exc);
163
Guido van Rossum30944842000-03-10 22:32:23 +0000164#ifdef __cplusplus
165}
166#endif
167#endif /* !Py_CODECREGISTRY_H */