/Include/codecs.h

  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 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
 48PyAPI_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
 62PyAPI_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
 78PyAPI_FUNC(PyObject *) PyCodec_Decode(
 79       PyObject *object,
 80       const char *encoding,
 81       const char *errors
 82       );
 83
 84/* --- 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
 94PyAPI_FUNC(PyObject *) PyCodec_Encoder(
 95       const char *encoding
 96       );
 97
 98/* Get a decoder function for the given encoding. */
 99
100PyAPI_FUNC(PyObject *) PyCodec_Decoder(
101       const char *encoding
102       );
103
104/* 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
118/* Get a StreamReader factory function for the given encoding. */
119
120PyAPI_FUNC(PyObject *) PyCodec_StreamReader(
121       const char *encoding,
122       PyObject *stream,
123       const char *errors
124       );
125
126/* Get a StreamWriter factory function for the given encoding. */
127
128PyAPI_FUNC(PyObject *) PyCodec_StreamWriter(
129       const char *encoding,
130       PyObject *stream,
131       const char *errors
132       );
133
134/* 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
164#ifdef __cplusplus
165}
166#endif
167#endif /* !Py_CODECREGISTRY_H */