Include/codecs.h

   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 registry 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 /* 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
  59 PyAPI_FUNC(int) PyCodec_KnownEncoding(
  60        const char *encoding
  61        );
  62
  63 /* Generic codec based encoding API.
  64
  65    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.
  70
  71  */
  72
  73 PyAPI_FUNC(PyObject *) PyCodec_Encode(
  74        PyObject *object,
  75        const char *encoding,
  76        const char *errors
  77        );
  78
  79 /* 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
  89 PyAPI_FUNC(PyObject *) PyCodec_Decode(
  90        PyObject *object,
  91        const char *encoding,
  92        const char *errors
  93        );
  94
  95 /* --- 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
 105 PyAPI_FUNC(PyObject *) PyCodec_Encoder(
 106        const char *encoding
 107        );
 108
 109 /* Get a decoder function for the given encoding. */
 110
 111 PyAPI_FUNC(PyObject *) PyCodec_Decoder(
 112        const char *encoding
 113        );
 114
 115 /* Get a IncrementalEncoder object for the given encoding. */
 116
 117 PyAPI_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
 124 PyAPI_FUNC(PyObject *) PyCodec_IncrementalDecoder(
 125        const char *encoding,
 126        const char *errors
 127        );
 128
 129 /* Get a StreamReader factory function for the given encoding. */
 130
 131 PyAPI_FUNC(PyObject *) PyCodec_StreamReader(
 132        const char *encoding,
 133        PyObject *stream,
 134        const char *errors
 135        );
 136
 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        const char *errors
 143        );
 144
 145 /* Unicode encoding error handling callback registry API */
 146
 147 /* Register the error handling callback function error under the name
 148    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 */
 153 PyAPI_FUNC(int) PyCodec_RegisterError(const char *name, PyObject *error);
 154
 155 /* Lookup the error handling callback function registered under the
 156    name error. As a special case NULL can be passed, in which case
 157    the error handling callback for "strict" will be returned. */
 158 PyAPI_FUNC(PyObject *) PyCodec_LookupError(const char *name);
 159
 160 /* raise exc as an exception */
 161 PyAPI_FUNC(PyObject *) PyCodec_StrictErrors(PyObject *exc);
 162
 163 /* ignore the unicode error, skipping the faulty input */
 164 PyAPI_FUNC(PyObject *) PyCodec_IgnoreErrors(PyObject *exc);
 165
 166 /* replace the unicode error with ? or U+FFFD */
 167 PyAPI_FUNC(PyObject *) PyCodec_ReplaceErrors(PyObject *exc);
 168
 169 /* replace the unicode encode error with XML character references */
 170 PyAPI_FUNC(PyObject *) PyCodec_XMLCharRefReplaceErrors(PyObject *exc);
 171
 172 /* replace the unicode encode error with backslash escapes (\x, \u and \U) */
 173 PyAPI_FUNC(PyObject *) PyCodec_BackslashReplaceErrors(PyObject *exc);
 174
 175 #ifdef __cplusplus
 176 }
 177 #endif
 178 #endif /* !Py_CODECREGISTRY_H */