Chris@87: #ifndef Py_CODECREGISTRY_H
Chris@87: #define Py_CODECREGISTRY_H
Chris@87: #ifdef __cplusplus
Chris@87: extern "C" {
Chris@87: #endif
Chris@87: 
Chris@87: /* ------------------------------------------------------------------------
Chris@87: 
Chris@87:    Python Codec Registry and support functions
Chris@87: 
Chris@87: 
Chris@87: Written by Marc-Andre Lemburg (mal@lemburg.com).
Chris@87: 
Chris@87: Copyright (c) Corporation for National Research Initiatives.
Chris@87: 
Chris@87:    ------------------------------------------------------------------------ */
Chris@87: 
Chris@87: /* Register a new codec search function.
Chris@87: 
Chris@87:    As side effect, this tries to load the encodings package, if not
Chris@87:    yet done, to make sure that it is always first in the list of
Chris@87:    search functions.
Chris@87: 
Chris@87:    The search_function's refcount is incremented by this function. */
Chris@87: 
Chris@87: PyAPI_FUNC(int) PyCodec_Register(
Chris@87:        PyObject *search_function
Chris@87:        );
Chris@87: 
Chris@87: /* Codec register lookup API.
Chris@87: 
Chris@87:    Looks up the given encoding and returns a CodecInfo object with
Chris@87:    function attributes which implement the different aspects of
Chris@87:    processing the encoding.
Chris@87: 
Chris@87:    The encoding string is looked up converted to all lower-case
Chris@87:    characters. This makes encodings looked up through this mechanism
Chris@87:    effectively case-insensitive.
Chris@87: 
Chris@87:    If no codec is found, a KeyError is set and NULL returned.
Chris@87: 
Chris@87:    As side effect, this tries to load the encodings package, if not
Chris@87:    yet done. This is part of the lazy load strategy for the encodings
Chris@87:    package.
Chris@87: 
Chris@87:  */
Chris@87: 
Chris@87: PyAPI_FUNC(PyObject *) _PyCodec_Lookup(
Chris@87:        const char *encoding
Chris@87:        );
Chris@87: 
Chris@87: /* Generic codec based encoding API.
Chris@87: 
Chris@87:    object is passed through the encoder function found for the given
Chris@87:    encoding using the error handling method defined by errors. errors
Chris@87:    may be NULL to use the default method defined for the codec.
Chris@87:    
Chris@87:    Raises a LookupError in case no encoder can be found.
Chris@87: 
Chris@87:  */
Chris@87: 
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_Encode(
Chris@87:        PyObject *object,
Chris@87:        const char *encoding,
Chris@87:        const char *errors
Chris@87:        );
Chris@87: 
Chris@87: /* Generic codec based decoding API.
Chris@87: 
Chris@87:    object is passed through the decoder function found for the given
Chris@87:    encoding using the error handling method defined by errors. errors
Chris@87:    may be NULL to use the default method defined for the codec.
Chris@87:    
Chris@87:    Raises a LookupError in case no encoder can be found.
Chris@87: 
Chris@87:  */
Chris@87: 
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_Decode(
Chris@87:        PyObject *object,
Chris@87:        const char *encoding,
Chris@87:        const char *errors
Chris@87:        );
Chris@87: 
Chris@87: /* --- Codec Lookup APIs -------------------------------------------------- 
Chris@87: 
Chris@87:    All APIs return a codec object with incremented refcount and are
Chris@87:    based on _PyCodec_Lookup().  The same comments w/r to the encoding
Chris@87:    name also apply to these APIs.
Chris@87: 
Chris@87: */
Chris@87: 
Chris@87: /* Get an encoder function for the given encoding. */
Chris@87: 
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_Encoder(
Chris@87:        const char *encoding
Chris@87:        );
Chris@87: 
Chris@87: /* Get a decoder function for the given encoding. */
Chris@87: 
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_Decoder(
Chris@87:        const char *encoding
Chris@87:        );
Chris@87: 
Chris@87: /* Get a IncrementalEncoder object for the given encoding. */
Chris@87: 
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_IncrementalEncoder(
Chris@87:        const char *encoding,
Chris@87:        const char *errors
Chris@87:        );
Chris@87: 
Chris@87: /* Get a IncrementalDecoder object function for the given encoding. */
Chris@87: 
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_IncrementalDecoder(
Chris@87:        const char *encoding,
Chris@87:        const char *errors
Chris@87:        );
Chris@87: 
Chris@87: /* Get a StreamReader factory function for the given encoding. */
Chris@87: 
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_StreamReader(
Chris@87:        const char *encoding,
Chris@87:        PyObject *stream,
Chris@87:        const char *errors
Chris@87:        );
Chris@87: 
Chris@87: /* Get a StreamWriter factory function for the given encoding. */
Chris@87: 
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_StreamWriter(
Chris@87:        const char *encoding,
Chris@87:        PyObject *stream,
Chris@87:        const char *errors
Chris@87:        );
Chris@87: 
Chris@87: /* Unicode encoding error handling callback registry API */
Chris@87: 
Chris@87: /* Register the error handling callback function error under the given
Chris@87:    name. This function will be called by the codec when it encounters
Chris@87:    unencodable characters/undecodable bytes and doesn't know the
Chris@87:    callback name, when name is specified as the error parameter
Chris@87:    in the call to the encode/decode function.
Chris@87:    Return 0 on success, -1 on error */
Chris@87: PyAPI_FUNC(int) PyCodec_RegisterError(const char *name, PyObject *error);
Chris@87: 
Chris@87: /* Lookup the error handling callback function registered under the given
Chris@87:    name. As a special case NULL can be passed, in which case
Chris@87:    the error handling callback for "strict" will be returned. */
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_LookupError(const char *name);
Chris@87: 
Chris@87: /* raise exc as an exception */
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_StrictErrors(PyObject *exc);
Chris@87: 
Chris@87: /* ignore the unicode error, skipping the faulty input */
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_IgnoreErrors(PyObject *exc);
Chris@87: 
Chris@87: /* replace the unicode encode error with ? or U+FFFD */
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_ReplaceErrors(PyObject *exc);
Chris@87: 
Chris@87: /* replace the unicode encode error with XML character references */
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_XMLCharRefReplaceErrors(PyObject *exc);
Chris@87: 
Chris@87: /* replace the unicode encode error with backslash escapes (\x, \u and \U) */
Chris@87: PyAPI_FUNC(PyObject *) PyCodec_BackslashReplaceErrors(PyObject *exc);
Chris@87: 
Chris@87: #ifdef __cplusplus
Chris@87: }
Chris@87: #endif
Chris@87: #endif /* !Py_CODECREGISTRY_H */