jpayne@69: #ifndef Py_CODECREGISTRY_H
jpayne@69: #define Py_CODECREGISTRY_H
jpayne@69: #ifdef __cplusplus
jpayne@69: extern "C" {
jpayne@69: #endif
jpayne@69: 
jpayne@69: /* ------------------------------------------------------------------------
jpayne@69: 
jpayne@69:    Python Codec Registry and support functions
jpayne@69: 
jpayne@69: 
jpayne@69: Written by Marc-Andre Lemburg (mal@lemburg.com).
jpayne@69: 
jpayne@69: Copyright (c) Corporation for National Research Initiatives.
jpayne@69: 
jpayne@69:    ------------------------------------------------------------------------ */
jpayne@69: 
jpayne@69: /* Register a new codec search function.
jpayne@69: 
jpayne@69:    As side effect, this tries to load the encodings package, if not
jpayne@69:    yet done, to make sure that it is always first in the list of
jpayne@69:    search functions.
jpayne@69: 
jpayne@69:    The search_function's refcount is incremented by this function. */
jpayne@69: 
jpayne@69: PyAPI_FUNC(int) PyCodec_Register(
jpayne@69:        PyObject *search_function
jpayne@69:        );
jpayne@69: 
jpayne@69: /* Codec registry lookup API.
jpayne@69: 
jpayne@69:    Looks up the given encoding and returns a CodecInfo object with
jpayne@69:    function attributes which implement the different aspects of
jpayne@69:    processing the encoding.
jpayne@69: 
jpayne@69:    The encoding string is looked up converted to all lower-case
jpayne@69:    characters. This makes encodings looked up through this mechanism
jpayne@69:    effectively case-insensitive.
jpayne@69: 
jpayne@69:    If no codec is found, a KeyError is set and NULL returned.
jpayne@69: 
jpayne@69:    As side effect, this tries to load the encodings package, if not
jpayne@69:    yet done. This is part of the lazy load strategy for the encodings
jpayne@69:    package.
jpayne@69: 
jpayne@69:  */
jpayne@69: 
jpayne@69: #ifndef Py_LIMITED_API
jpayne@69: PyAPI_FUNC(PyObject *) _PyCodec_Lookup(
jpayne@69:        const char *encoding
jpayne@69:        );
jpayne@69: 
jpayne@69: PyAPI_FUNC(int) _PyCodec_Forget(
jpayne@69:        const char *encoding
jpayne@69:        );
jpayne@69: #endif
jpayne@69: 
jpayne@69: /* Codec registry encoding check API.
jpayne@69: 
jpayne@69:    Returns 1/0 depending on whether there is a registered codec for
jpayne@69:    the given encoding.
jpayne@69: 
jpayne@69: */
jpayne@69: 
jpayne@69: PyAPI_FUNC(int) PyCodec_KnownEncoding(
jpayne@69:        const char *encoding
jpayne@69:        );
jpayne@69: 
jpayne@69: /* Generic codec based encoding API.
jpayne@69: 
jpayne@69:    object is passed through the encoder function found for the given
jpayne@69:    encoding using the error handling method defined by errors. errors
jpayne@69:    may be NULL to use the default method defined for the codec.
jpayne@69: 
jpayne@69:    Raises a LookupError in case no encoder can be found.
jpayne@69: 
jpayne@69:  */
jpayne@69: 
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_Encode(
jpayne@69:        PyObject *object,
jpayne@69:        const char *encoding,
jpayne@69:        const char *errors
jpayne@69:        );
jpayne@69: 
jpayne@69: /* Generic codec based decoding API.
jpayne@69: 
jpayne@69:    object is passed through the decoder function found for the given
jpayne@69:    encoding using the error handling method defined by errors. errors
jpayne@69:    may be NULL to use the default method defined for the codec.
jpayne@69: 
jpayne@69:    Raises a LookupError in case no encoder can be found.
jpayne@69: 
jpayne@69:  */
jpayne@69: 
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_Decode(
jpayne@69:        PyObject *object,
jpayne@69:        const char *encoding,
jpayne@69:        const char *errors
jpayne@69:        );
jpayne@69: 
jpayne@69: #ifndef Py_LIMITED_API
jpayne@69: /* Text codec specific encoding and decoding API.
jpayne@69: 
jpayne@69:    Checks the encoding against a list of codecs which do not
jpayne@69:    implement a str<->bytes encoding before attempting the
jpayne@69:    operation.
jpayne@69: 
jpayne@69:    Please note that these APIs are internal and should not
jpayne@69:    be used in Python C extensions.
jpayne@69: 
jpayne@69:    XXX (ncoghlan): should we make these, or something like them, public
jpayne@69:    in Python 3.5+?
jpayne@69: 
jpayne@69:  */
jpayne@69: PyAPI_FUNC(PyObject *) _PyCodec_LookupTextEncoding(
jpayne@69:        const char *encoding,
jpayne@69:        const char *alternate_command
jpayne@69:        );
jpayne@69: 
jpayne@69: PyAPI_FUNC(PyObject *) _PyCodec_EncodeText(
jpayne@69:        PyObject *object,
jpayne@69:        const char *encoding,
jpayne@69:        const char *errors
jpayne@69:        );
jpayne@69: 
jpayne@69: PyAPI_FUNC(PyObject *) _PyCodec_DecodeText(
jpayne@69:        PyObject *object,
jpayne@69:        const char *encoding,
jpayne@69:        const char *errors
jpayne@69:        );
jpayne@69: 
jpayne@69: /* These two aren't actually text encoding specific, but _io.TextIOWrapper
jpayne@69:  * is the only current API consumer.
jpayne@69:  */
jpayne@69: PyAPI_FUNC(PyObject *) _PyCodecInfo_GetIncrementalDecoder(
jpayne@69:        PyObject *codec_info,
jpayne@69:        const char *errors
jpayne@69:        );
jpayne@69: 
jpayne@69: PyAPI_FUNC(PyObject *) _PyCodecInfo_GetIncrementalEncoder(
jpayne@69:        PyObject *codec_info,
jpayne@69:        const char *errors
jpayne@69:        );
jpayne@69: #endif
jpayne@69: 
jpayne@69: 
jpayne@69: 
jpayne@69: /* --- Codec Lookup APIs --------------------------------------------------
jpayne@69: 
jpayne@69:    All APIs return a codec object with incremented refcount and are
jpayne@69:    based on _PyCodec_Lookup().  The same comments w/r to the encoding
jpayne@69:    name also apply to these APIs.
jpayne@69: 
jpayne@69: */
jpayne@69: 
jpayne@69: /* Get an encoder function for the given encoding. */
jpayne@69: 
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_Encoder(
jpayne@69:        const char *encoding
jpayne@69:        );
jpayne@69: 
jpayne@69: /* Get a decoder function for the given encoding. */
jpayne@69: 
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_Decoder(
jpayne@69:        const char *encoding
jpayne@69:        );
jpayne@69: 
jpayne@69: /* Get an IncrementalEncoder object for the given encoding. */
jpayne@69: 
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_IncrementalEncoder(
jpayne@69:        const char *encoding,
jpayne@69:        const char *errors
jpayne@69:        );
jpayne@69: 
jpayne@69: /* Get an IncrementalDecoder object function for the given encoding. */
jpayne@69: 
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_IncrementalDecoder(
jpayne@69:        const char *encoding,
jpayne@69:        const char *errors
jpayne@69:        );
jpayne@69: 
jpayne@69: /* Get a StreamReader factory function for the given encoding. */
jpayne@69: 
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_StreamReader(
jpayne@69:        const char *encoding,
jpayne@69:        PyObject *stream,
jpayne@69:        const char *errors
jpayne@69:        );
jpayne@69: 
jpayne@69: /* Get a StreamWriter factory function for the given encoding. */
jpayne@69: 
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_StreamWriter(
jpayne@69:        const char *encoding,
jpayne@69:        PyObject *stream,
jpayne@69:        const char *errors
jpayne@69:        );
jpayne@69: 
jpayne@69: /* Unicode encoding error handling callback registry API */
jpayne@69: 
jpayne@69: /* Register the error handling callback function error under the given
jpayne@69:    name. This function will be called by the codec when it encounters
jpayne@69:    unencodable characters/undecodable bytes and doesn't know the
jpayne@69:    callback name, when name is specified as the error parameter
jpayne@69:    in the call to the encode/decode function.
jpayne@69:    Return 0 on success, -1 on error */
jpayne@69: PyAPI_FUNC(int) PyCodec_RegisterError(const char *name, PyObject *error);
jpayne@69: 
jpayne@69: /* Lookup the error handling callback function registered under the given
jpayne@69:    name. As a special case NULL can be passed, in which case
jpayne@69:    the error handling callback for "strict" will be returned. */
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_LookupError(const char *name);
jpayne@69: 
jpayne@69: /* raise exc as an exception */
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_StrictErrors(PyObject *exc);
jpayne@69: 
jpayne@69: /* ignore the unicode error, skipping the faulty input */
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_IgnoreErrors(PyObject *exc);
jpayne@69: 
jpayne@69: /* replace the unicode encode error with ? or U+FFFD */
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_ReplaceErrors(PyObject *exc);
jpayne@69: 
jpayne@69: /* replace the unicode encode error with XML character references */
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_XMLCharRefReplaceErrors(PyObject *exc);
jpayne@69: 
jpayne@69: /* replace the unicode encode error with backslash escapes (\x, \u and \U) */
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_BackslashReplaceErrors(PyObject *exc);
jpayne@69: 
jpayne@69: #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
jpayne@69: /* replace the unicode encode error with backslash escapes (\N, \x, \u and \U) */
jpayne@69: PyAPI_FUNC(PyObject *) PyCodec_NameReplaceErrors(PyObject *exc);
jpayne@69: #endif
jpayne@69: 
jpayne@69: #ifndef Py_LIMITED_API
jpayne@69: PyAPI_DATA(const char *) Py_hexdigits;
jpayne@69: #endif
jpayne@69: 
jpayne@69: #ifdef __cplusplus
jpayne@69: }
jpayne@69: #endif
jpayne@69: #endif /* !Py_CODECREGISTRY_H */