1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
|
<span id="codec-registry"></span><h1>Codec registry and support functions</h1> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_Register">
<code>int PyCodec_Register(PyObject *search_function)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Register a new codec search function.</p> <p>As side effect, this tries to load the <code>encodings</code> package, if not yet done, to make sure that it is always first in the list of search functions.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_Unregister">
<code>int PyCodec_Unregister(PyObject *search_function)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>Unregister a codec search function and clear the registry’s cache. If the search function is not registered, do nothing. Return 0 on success. Raise an exception and return -1 on error.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_KnownEncoding">
<code>int PyCodec_KnownEncoding(const char *encoding)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return <code>1</code> or <code>0</code> depending on whether there is a registered codec for the given <em>encoding</em>. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_Encode">
<code>PyObject *PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Generic codec based encoding API.</p> <p><em>object</em> is passed through the encoder function found for the given <em>encoding</em> using the error handling method defined by <em>errors</em>. <em>errors</em> may be <code>NULL</code> to use the default method defined for the codec. Raises a <a class="reference internal" href="../library/exceptions#LookupError" title="LookupError"><code>LookupError</code></a> if no encoder can be found.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_Decode">
<code>PyObject *PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Generic codec based decoding API.</p> <p><em>object</em> is passed through the decoder function found for the given <em>encoding</em> using the error handling method defined by <em>errors</em>. <em>errors</em> may be <code>NULL</code> to use the default method defined for the codec. Raises a <a class="reference internal" href="../library/exceptions#LookupError" title="LookupError"><code>LookupError</code></a> if no encoder can be found.</p> </dd>
</dl> <section id="codec-lookup-api"> <h2>Codec lookup API</h2> <p>In the following functions, the <em>encoding</em> string is looked up converted to all lower-case characters, which makes encodings looked up through this mechanism effectively case-insensitive. If no codec is found, a <a class="reference internal" href="../library/exceptions#KeyError" title="KeyError"><code>KeyError</code></a> is set and <code>NULL</code> returned.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_Encoder">
<code>PyObject *PyCodec_Encoder(const char *encoding)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Get an encoder function for the given <em>encoding</em>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_Decoder">
<code>PyObject *PyCodec_Decoder(const char *encoding)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Get a decoder function for the given <em>encoding</em>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_IncrementalEncoder">
<code>PyObject *PyCodec_IncrementalEncoder(const char *encoding, const char *errors)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Get an <a class="reference internal" href="../library/codecs#codecs.IncrementalEncoder" title="codecs.IncrementalEncoder"><code>IncrementalEncoder</code></a> object for the given <em>encoding</em>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_IncrementalDecoder">
<code>PyObject *PyCodec_IncrementalDecoder(const char *encoding, const char *errors)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Get an <a class="reference internal" href="../library/codecs#codecs.IncrementalDecoder" title="codecs.IncrementalDecoder"><code>IncrementalDecoder</code></a> object for the given <em>encoding</em>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_StreamReader">
<code>PyObject *PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Get a <a class="reference internal" href="../library/codecs#codecs.StreamReader" title="codecs.StreamReader"><code>StreamReader</code></a> factory function for the given <em>encoding</em>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_StreamWriter">
<code>PyObject *PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Get a <a class="reference internal" href="../library/codecs#codecs.StreamWriter" title="codecs.StreamWriter"><code>StreamWriter</code></a> factory function for the given <em>encoding</em>.</p> </dd>
</dl> </section> <section id="registry-api-for-unicode-encoding-error-handlers"> <h2>Registry API for Unicode encoding error handlers</h2> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_RegisterError">
<code>int PyCodec_RegisterError(const char *name, PyObject *error)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Register the error handling callback function <em>error</em> under the given <em>name</em>. This callback function will be called by a codec when it encounters unencodable characters/undecodable bytes and <em>name</em> is specified as the error parameter in the call to the encode/decode function.</p> <p>The callback gets a single argument, an instance of <a class="reference internal" href="../library/exceptions#UnicodeEncodeError" title="UnicodeEncodeError"><code>UnicodeEncodeError</code></a>, <a class="reference internal" href="../library/exceptions#UnicodeDecodeError" title="UnicodeDecodeError"><code>UnicodeDecodeError</code></a> or <a class="reference internal" href="../library/exceptions#UnicodeTranslateError" title="UnicodeTranslateError"><code>UnicodeTranslateError</code></a> that holds information about the problematic sequence of characters or bytes and their offset in the original string (see <a class="reference internal" href="exceptions#unicodeexceptions"><span class="std std-ref">Unicode Exception Objects</span></a> for functions to extract this information). The callback must either raise the given exception, or return a two-item tuple containing the replacement for the problematic sequence, and an integer giving the offset in the original string at which encoding/decoding should be resumed.</p> <p>Return <code>0</code> on success, <code>-1</code> on error.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_LookupError">
<code>PyObject *PyCodec_LookupError(const char *name)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Lookup the error handling callback function registered under <em>name</em>. As a special case <code>NULL</code> can be passed, in which case the error handling callback for “strict” will be returned.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_StrictErrors">
<code>PyObject *PyCodec_StrictErrors(PyObject *exc)</code> </dt> <dd>
<em class="refcount">Return value: Always NULL.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Raise <em>exc</em> as an exception.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_IgnoreErrors">
<code>PyObject *PyCodec_IgnoreErrors(PyObject *exc)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Ignore the unicode error, skipping the faulty input.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_ReplaceErrors">
<code>PyObject *PyCodec_ReplaceErrors(PyObject *exc)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Replace the unicode encode error with <code>?</code> or <code>U+FFFD</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_XMLCharRefReplaceErrors">
<code>PyObject *PyCodec_XMLCharRefReplaceErrors(PyObject *exc)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Replace the unicode encode error with XML character references.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_BackslashReplaceErrors">
<code>PyObject *PyCodec_BackslashReplaceErrors(PyObject *exc)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Replace the unicode encode error with backslash escapes (<code>\x</code>, <code>\u</code> and <code>\U</code>).</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCodec_NameReplaceErrors">
<code>PyObject *PyCodec_NameReplaceErrors(PyObject *exc)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Replace the unicode encode error with <code>\N{...}</code> escapes.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5.</span></p> </div> </dd>
</dl> </section> <div class="_attribution">
<p class="_attribution-p">
© 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br>
<a href="https://docs.python.org/3.12/c-api/codec.html" class="_attribution-link">https://docs.python.org/3.12/c-api/codec.html</a>
</p>
</div>
|
