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 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 /* --- 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
  94 PyAPI_FUNC(PyObject *) PyCodec_Encoder(
  95        const char *encoding
  96        );
  97
  98 /* Get a decoder function for the given encoding. */
  99
 100 PyAPI_FUNC(PyObject *) PyCodec_Decoder(
 101        const char *encoding
 102        );
 103
 104 /* Get a IncrementalEncoder object for the given encoding. */
 105
 106 PyAPI_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
 113 PyAPI_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
 120 PyAPI_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
 128 PyAPI_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 */
 142 PyAPI_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. */
 147 PyAPI_FUNC(PyObject *) PyCodec_LookupError(const char *name);
 148
 149 /* raise exc as an exception */
 150 PyAPI_FUNC(PyObject *) PyCodec_StrictErrors(PyObject *exc);
 151
 152 /* ignore the unicode error, skipping the faulty input */
 153 PyAPI_FUNC(PyObject *) PyCodec_IgnoreErrors(PyObject *exc);
 154
 155 /* replace the unicode error with ? or U+FFFD */
 156 PyAPI_FUNC(PyObject *) PyCodec_ReplaceErrors(PyObject *exc);
 157
 158 /* replace the unicode encode error with XML character references */
 159 PyAPI_FUNC(PyObject *) PyCodec_XMLCharRefReplaceErrors(PyObject *exc);
 160
 161 /* replace the unicode encode error with backslash escapes (\x, \u and \U) */
 162 PyAPI_FUNC(PyObject *) PyCodec_BackslashReplaceErrors(PyObject *exc);
 163
 164 #ifdef __cplusplus
 165 }
 166 #endif
 167 #endif /* !Py_CODECREGISTRY_H */