python-2.7.11/Include/codecs.h Source File

codecs.h
Go to the documentation of this file.
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 /* Text codec specific encoding and decoding API.
85 
86  Checks the encoding against a list of codecs which do not
87  implement a unicode<->bytes encoding before attempting the
88  operation.
89 
90  Please note that these APIs are internal and should not
91  be used in Python C extensions.
92 
93  XXX (ncoghlan): should we make these, or something like them, public
94  in Python 3.5+?
95 
96  */
97 PyAPI_FUNC(PyObject *) _PyCodec_LookupTextEncoding(
98  const char *encoding,
99  const char *alternate_command
100  );
101 
102 PyAPI_FUNC(PyObject *) _PyCodec_EncodeText(
103  PyObject *object,
104  const char *encoding,
105  const char *errors
106  );
107 
108 PyAPI_FUNC(PyObject *) _PyCodec_DecodeText(
109  PyObject *object,
110  const char *encoding,
111  const char *errors
112  );
113 
114 /* These two aren't actually text encoding specific, but _io.TextIOWrapper
115  * is the only current API consumer.
116  */
117 PyAPI_FUNC(PyObject *) _PyCodecInfo_GetIncrementalDecoder(
118  PyObject *codec_info,
119  const char *errors
120  );
121 
122 PyAPI_FUNC(PyObject *) _PyCodecInfo_GetIncrementalEncoder(
123  PyObject *codec_info,
124  const char *errors
125  );
126 
127 
128 
129 /* --- Codec Lookup APIs --------------------------------------------------
130 
131  All APIs return a codec object with incremented refcount and are
132  based on _PyCodec_Lookup(). The same comments w/r to the encoding
133  name also apply to these APIs.
134 
135 */
136 
137 /* Get an encoder function for the given encoding. */
138 
139 PyAPI_FUNC(PyObject *) PyCodec_Encoder(
140  const char *encoding
141  );
142 
143 /* Get a decoder function for the given encoding. */
144 
145 PyAPI_FUNC(PyObject *) PyCodec_Decoder(
146  const char *encoding
147  );
148 
149 /* Get a IncrementalEncoder object for the given encoding. */
150 
151 PyAPI_FUNC(PyObject *) PyCodec_IncrementalEncoder(
152  const char *encoding,
153  const char *errors
154  );
155 
156 /* Get a IncrementalDecoder object function for the given encoding. */
157 
158 PyAPI_FUNC(PyObject *) PyCodec_IncrementalDecoder(
159  const char *encoding,
160  const char *errors
161  );
162 
163 /* Get a StreamReader factory function for the given encoding. */
164 
165 PyAPI_FUNC(PyObject *) PyCodec_StreamReader(
166  const char *encoding,
168  const char *errors
169  );
170 
171 /* Get a StreamWriter factory function for the given encoding. */
172 
173 PyAPI_FUNC(PyObject *) PyCodec_StreamWriter(
174  const char *encoding,
175  PyObject *stream,
176  const char *errors
177  );
178 
179 /* Unicode encoding error handling callback registry API */
180 
181 /* Register the error handling callback function error under the given
182  name. This function will be called by the codec when it encounters
183  unencodable characters/undecodable bytes and doesn't know the
184  callback name, when name is specified as the error parameter
185  in the call to the encode/decode function.
186  Return 0 on success, -1 on error */
187 PyAPI_FUNC(int) PyCodec_RegisterError(const char *name, PyObject *error);
188 
189 /* Lookup the error handling callback function registered under the given
190  name. As a special case NULL can be passed, in which case
191  the error handling callback for "strict" will be returned. */
192 PyAPI_FUNC(PyObject *) PyCodec_LookupError(const char *name);
193 
194 /* raise exc as an exception */
195 PyAPI_FUNC(PyObject *) PyCodec_StrictErrors(PyObject *exc);
196 
197 /* ignore the unicode error, skipping the faulty input */
198 PyAPI_FUNC(PyObject *) PyCodec_IgnoreErrors(PyObject *exc);
199 
200 /* replace the unicode encode error with ? or U+FFFD */
201 PyAPI_FUNC(PyObject *) PyCodec_ReplaceErrors(PyObject *exc);
202 
203 /* replace the unicode encode error with XML character references */
204 PyAPI_FUNC(PyObject *) PyCodec_XMLCharRefReplaceErrors(PyObject *exc);
205 
206 /* replace the unicode encode error with backslash escapes (\x, \u and \U) */
207 PyAPI_FUNC(PyObject *) PyCodec_BackslashReplaceErrors(PyObject *exc);
208 
209 #ifdef __cplusplus
210 }
211 #endif
212 #endif /* !Py_CODECREGISTRY_H */
const char * encoding
Definition: codecs.h:64
const char * alternate_command
Definition: codecs.h:100
PyAPI_FUNC(int) PyCodec_Register(PyObject *search_function)
char char char char char * name
Definition: abstract.h:355
PyObject * exc
Definition: abstract.h:860
PyObject * error
Definition: codecs.h:187
PyObject * stream
Definition: codecs.h:167
const char const char * errors
Definition: codecs.h:64