codecs.h 5.1 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13
#ifndef Py_CODECREGISTRY_H
#define Py_CODECREGISTRY_H
#ifdef __cplusplus
extern "C" {
#endif

/* ------------------------------------------------------------------------

   Python Codec Registry and support functions


Written by Marc-Andre Lemburg (mal@lemburg.com).

14
Copyright (c) Corporation for National Research Initiatives.
15 16 17

   ------------------------------------------------------------------------ */

18 19 20 21 22 23 24 25
/* Register a new codec search function.

   As side effect, this tries to load the encodings package, if not
   yet done, to make sure that it is always first in the list of
   search functions.

   The search_function's refcount is incremented by this function. */

26
PyAPI_FUNC(int) PyCodec_Register(
27 28 29
       PyObject *search_function
       );

30
/* Codec registry lookup API.
31

32 33 34
   Looks up the given encoding and returns a CodecInfo object with
   function attributes which implement the different aspects of
   processing the encoding.
35 36 37 38 39

   The encoding string is looked up converted to all lower-case
   characters. This makes encodings looked up through this mechanism
   effectively case-insensitive.

40
   If no codec is found, a KeyError is set and NULL returned.
41 42 43 44 45 46 47

   As side effect, this tries to load the encodings package, if not
   yet done. This is part of the lazy load strategy for the encodings
   package.

 */

48
PyAPI_FUNC(PyObject *) _PyCodec_Lookup(
49 50 51
       const char *encoding
       );

52 53 54 55 56 57 58 59 60 61 62
/* Codec registry encoding check API.

   Returns 1/0 depending on whether there is a registered codec for
   the given encoding.

*/

PyAPI_FUNC(int) PyCodec_KnownEncoding(
       const char *encoding
       );

63 64 65 66 67 68 69 70 71 72
/* Generic codec based encoding API.

   object is passed through the encoder function found for the given
   encoding using the error handling method defined by errors. errors
   may be NULL to use the default method defined for the codec.
   
   Raises a LookupError in case no encoder can be found.

 */

73
PyAPI_FUNC(PyObject *) PyCodec_Encode(
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
       PyObject *object,
       const char *encoding,
       const char *errors
       );

/* Generic codec based decoding API.

   object is passed through the decoder function found for the given
   encoding using the error handling method defined by errors. errors
   may be NULL to use the default method defined for the codec.
   
   Raises a LookupError in case no encoder can be found.

 */

89
PyAPI_FUNC(PyObject *) PyCodec_Decode(
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104
       PyObject *object,
       const char *encoding,
       const char *errors
       );

/* --- Codec Lookup APIs -------------------------------------------------- 

   All APIs return a codec object with incremented refcount and are
   based on _PyCodec_Lookup().  The same comments w/r to the encoding
   name also apply to these APIs.

*/

/* Get an encoder function for the given encoding. */

105
PyAPI_FUNC(PyObject *) PyCodec_Encoder(
106 107 108
       const char *encoding
       );

109 110
/* Get a decoder function for the given encoding. */

111
PyAPI_FUNC(PyObject *) PyCodec_Decoder(
112 113 114
       const char *encoding
       );

115 116 117 118 119 120 121 122 123 124 125 126 127 128
/* Get a IncrementalEncoder object for the given encoding. */

PyAPI_FUNC(PyObject *) PyCodec_IncrementalEncoder(
       const char *encoding,
       const char *errors
       );

/* Get a IncrementalDecoder object function for the given encoding. */

PyAPI_FUNC(PyObject *) PyCodec_IncrementalDecoder(
       const char *encoding,
       const char *errors
       );

129 130
/* Get a StreamReader factory function for the given encoding. */

131
PyAPI_FUNC(PyObject *) PyCodec_StreamReader(
132 133 134 135 136
       const char *encoding,
       PyObject *stream,
       const char *errors
       );

137
/* Get a StreamWriter factory function for the given encoding. */
138

139
PyAPI_FUNC(PyObject *) PyCodec_StreamWriter(
140
       const char *encoding,
141
       PyObject *stream,
142 143 144
       const char *errors
       );

145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
/* Unicode encoding error handling callback registry API */

/* Register the error handling callback function error under the name
   name. This function will be called by the codec when it encounters
   unencodable characters/undecodable bytes and doesn't know the
   callback name, when name is specified as the error parameter
   in the call to the encode/decode function.
   Return 0 on success, -1 on error */
PyAPI_FUNC(int) PyCodec_RegisterError(const char *name, PyObject *error);

/* Lookup the error handling callback function registered under the
   name error. As a special case NULL can be passed, in which case
   the error handling callback for "strict" will be returned. */
PyAPI_FUNC(PyObject *) PyCodec_LookupError(const char *name);

/* raise exc as an exception */
PyAPI_FUNC(PyObject *) PyCodec_StrictErrors(PyObject *exc);

/* ignore the unicode error, skipping the faulty input */
PyAPI_FUNC(PyObject *) PyCodec_IgnoreErrors(PyObject *exc);

/* replace the unicode error with ? or U+FFFD */
PyAPI_FUNC(PyObject *) PyCodec_ReplaceErrors(PyObject *exc);

/* replace the unicode encode error with XML character references */
PyAPI_FUNC(PyObject *) PyCodec_XMLCharRefReplaceErrors(PyObject *exc);

/* replace the unicode encode error with backslash escapes (\x, \u and \U) */
PyAPI_FUNC(PyObject *) PyCodec_BackslashReplaceErrors(PyObject *exc);

175 176 177 178
#ifdef __cplusplus
}
#endif
#endif /* !Py_CODECREGISTRY_H */