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