diff options
| -rw-r--r-- | Doc/api/api.tex | 132 |
1 files changed, 43 insertions, 89 deletions
diff --git a/Doc/api/api.tex b/Doc/api/api.tex index 04ddb00..faadd2a 100644 --- a/Doc/api/api.tex +++ b/Doc/api/api.tex @@ -1175,11 +1175,11 @@ For internal use only. For internal use only. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *} -Load a frozen module. Return \code{1} for success, \code{0} if the -module is not found, and \code{-1} with an exception set if the -initialization failed. To access the imported module on a successful -load, use \cfunction{PyImport_ImportModule()}. +\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name} +Load a frozen module named \var{name}. Return \code{1} for success, +\code{0} if the module is not found, and \code{-1} with an exception +set if the initialization failed. To access the imported module on a +successful load, use \cfunction{PyImport_ImportModule()}. (Note the misnomer --- this function would reload the module if it was already imported.) \end{cfuncdesc} @@ -2057,7 +2057,7 @@ undefined. It is the user's responsibility to fill in the needed data. The buffer is copied into the new object. \end{cfuncdesc} -\begin{cfuncdesc}{Py_UNICODE *}{PyUnicode_AsUnicode}{PyObject *unicode} +\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode} Return a read-only pointer to the Unicode object's internal \ctype{Py_UNICODE} buffer. \end{cfuncdesc} @@ -2102,7 +2102,6 @@ given size. Returns \NULL{} on failure. \begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode, wchar_t *w, int size} - Copies the Unicode Object contents into the \ctype{whcar_t} buffer \var{w}. At most \var{size} \ctype{whcar_t} characters are copied. Returns the number of \ctype{whcar_t} characters copied or -1 in case @@ -2138,7 +2137,6 @@ These are the generic codec APIs: int size, const char *encoding, const char *errors} - Create a Unicode object by decoding \var{size} bytes of the encoded string \var{s}. \var{encoding} and \var{errors} have the same meaning as the parameters of the same name in the unicode() builtin @@ -2151,7 +2149,6 @@ codec. int size, const char *encoding, const char *errors} - Encodes the \ctype{Py_UNICODE} buffer of the given size and returns a Python string object. \var{encoding} and \var{errors} have the same meaning as the parameters of the same name in the Unicode .encode() @@ -2163,7 +2160,6 @@ codec. \begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode, const char *encoding, const char *errors} - Encodes a Unicode object and returns the result as Python string object. \var{encoding} and \var{errors} have the same meaning as the parameters of the same name in the Unicode .encode() method. The codec @@ -2178,7 +2174,6 @@ These are the UTF-8 codec APIs: \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s, int size, const char *errors} - Creates a Unicode object by decoding \var{size} bytes of the UTF-8 encoded string \var{s}. Returns \NULL{} in case an exception was raised by the codec. @@ -2187,14 +2182,12 @@ raised by the codec. \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s, int size, const char *errors} - Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8 and returns a Python string object. Returns \NULL{} in case an exception was raised by the codec. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode} - Encodes a Unicode objects using UTF-8 and returns the result as Python string object. Error handling is ``strict''. Returns \NULL{} in case an exception was raised by the codec. @@ -2208,7 +2201,6 @@ These are the UTF-16 codec APIs: int size, const char *errors, int *byteorder} - Decodes \var{length} bytes from a UTF-16 encoded buffer string and returns the corresponding Unicode object. @@ -2238,7 +2230,6 @@ Returns \NULL{} in case an exception was raised by the codec. int size, const char *errors, int byteorder} - Returns a Python string object holding the UTF-16 encoded value of the Unicode data in \var{s}. @@ -2276,7 +2267,6 @@ These are the ``Unicode Esacpe'' codec APIs: \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s, int size, const char *errors} - Creates a Unicode object by decoding \var{size} bytes of the Unicode-Esacpe encoded string \var{s}. Returns \NULL{} in case an exception was raised by the codec. @@ -2285,14 +2275,12 @@ raised by the codec. \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s, int size, const char *errors} - Encodes the \ctype{Py_UNICODE} buffer of the given size using Unicode-Escape and returns a Python string object. Returns \NULL{} in case an exception was raised by the codec. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode} - Encodes a Unicode objects using Unicode-Escape and returns the result as Python string object. Error handling is ``strict''. Returns \NULL{} in case an exception was raised by the codec. @@ -2305,7 +2293,6 @@ These are the ``Raw Unicode Esacpe'' codec APIs: \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s, int size, const char *errors} - Creates a Unicode object by decoding \var{size} bytes of the Raw-Unicode-Esacpe encoded string \var{s}. Returns \NULL{} in case an exception was raised by the codec. @@ -2314,14 +2301,12 @@ raised by the codec. \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s, int size, const char *errors} - Encodes the \ctype{Py_UNICODE} buffer of the given size using Raw-Unicode-Escape and returns a Python string object. Returns \NULL{} in case an exception was raised by the codec. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode} - Encodes a Unicode objects using Raw-Unicode-Escape and returns the result as Python string object. Error handling is ``strict''. Returns \NULL{} in case an exception was raised by the codec. @@ -2335,25 +2320,22 @@ Latin-1 corresponds to the first 256 Unicode ordinals and only these are accepted by the codecs during encoding. \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s, - int size, - const char *errors} - + int size, + const char *errors} Creates a Unicode object by decoding \var{size} bytes of the Latin-1 encoded string \var{s}. Returns \NULL{} in case an exception was raised by the codec. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s, - int size, - const char *errors} - + int size, + const char *errors} Encodes the \ctype{Py_UNICODE} buffer of the given size using Latin-1 and returns a Python string object. Returns \NULL{} in case an exception was raised by the codec. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode} - Encodes a Unicode objects using Latin-1 and returns the result as Python string object. Error handling is ``strict''. Returns \NULL{} in case an exception was raised by the codec. @@ -2361,31 +2343,27 @@ Python string object. Error handling is ``strict''. Returns % --- ASCII Codecs ------------------------------------------------------- -These are the ASCII codec APIs: - -Only 7-bit ASCII data is excepted. All other codes generate errors. +These are the \ASCII{} codec APIs. Only 7-bit \ASCII{} data is +accepted. All other codes generate errors. \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s, - int size, - const char *errors} - -Creates a Unicode object by decoding \var{size} bytes of the ASCII -encoded string \var{s}. Returns \NULL{} in case an exception was -raised by the codec. + int size, + const char *errors} +Creates a Unicode object by decoding \var{size} bytes of the +\ASCII{} encoded string \var{s}. Returns \NULL{} in case an exception +was raised by the codec. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s, - int size, - const char *errors} - -Encodes the \ctype{Py_UNICODE} buffer of the given size using ASCII -and returns a Python string object. Returns \NULL{} in case an -exception was raised by the codec. + int size, + const char *errors} +Encodes the \ctype{Py_UNICODE} buffer of the given size using +\ASCII{} and returns a Python string object. Returns \NULL{} in case +an exception was raised by the codec. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode} - -Encodes a Unicode objects using ASCII and returns the result as Python +Encodes a Unicode objects using \ASCII{} and returns the result as Python string object. Error handling is ``strict''. Returns \NULL{} in case an exception was raised by the codec. \end{cfuncdesc} @@ -2420,7 +2398,6 @@ points. int size, PyObject *mapping, const char *errors} - Creates a Unicode object by decoding \var{size} bytes of the encoded string \var{s} using the given \var{mapping} object. Returns \NULL{} in case an exception was raised by the codec. @@ -2430,7 +2407,6 @@ in case an exception was raised by the codec. int size, PyObject *mapping, const char *errors} - Encodes the \ctype{Py_UNICODE} buffer of the given size using the given \var{mapping} object and returns a Python string object. Returns \NULL{} in case an exception was raised by the codec. @@ -2438,7 +2414,6 @@ Returns \NULL{} in case an exception was raised by the codec. \begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode, PyObject *mapping} - Encodes a Unicode objects using the given \var{mapping} object and returns the result as Python string object. Error handling is ``strict''. Returns \NULL{} in case an exception was raised by the @@ -2451,10 +2426,10 @@ The following codec API is special in that maps Unicode to Unicode. int size, PyObject *table, const char *errors} - Translates a \ctype{Py_UNICODE} buffer of the given length by applying a character mapping \var{table} to it and returns the resulting -Unicode object. +Unicode object. Returns \NULL{} when an exception was raised by the +codec. The \var{mapping} table must map Unicode ordinal integers to Unicode ordinal integers or None (causing deletion of the character). @@ -2462,43 +2437,36 @@ ordinal integers or None (causing deletion of the character). Mapping tables must only provide the __getitem__ interface, e.g. dictionaries or sequences. Unmapped character ordinals (ones which cause a LookupError) are left untouched and are copied as-is. - -Returns \NULL{} in case an exception was raised by the codec. \end{cfuncdesc} % --- MBCS codecs for Windows -------------------------------------------- -These are the MBCS codec APIs. They are currently only available +These are the MBCS codec APIs. They are currently only available on Windows and use the Win32 MBCS converters to implement the -conversions. - -Note that MBCS (or DBCS) is a class of encodings, not just one. The -target encoding is defined by the user settings on the machine running -the codec. +conversions. Note that MBCS (or DBCS) is a class of encodings, not +just one. The target encoding is defined by the user settings on the +machine running the codec. \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s, int size, const char *errors} - Creates a Unicode object by decoding \var{size} bytes of the MBCS -encoded string \var{s}. Returns \NULL{} in case an exception was +encoded string \var{s}. Returns \NULL{} in case an exception was raised by the codec. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s, int size, const char *errors} - Encodes the \ctype{Py_UNICODE} buffer of the given size using MBCS and returns a Python string object. Returns \NULL{} in case an exception was raised by the codec. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode} - Encodes a Unicode objects using MBCS and returns the result as Python -string object. Error handling is ``strict''. Returns -\NULL{} in case an exception was raised by the codec. +string object. Error handling is ``strict''. Returns \NULL{} in case +an exception was raised by the codec. \end{cfuncdesc} % --- Methods & Slots ---------------------------------------------------- @@ -2513,14 +2481,12 @@ They all return \NULL{} or -1 in case an exception occurrs. \begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left, PyObject *right} - Concat two strings giving a new Unicode string. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s, PyObject *sep, int maxsplit} - Split a string giving a list of Unicode strings. If sep is NULL, splitting will be done at all whitespace @@ -2533,17 +2499,14 @@ Separators are not included in the resulting list. \begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s, int maxsplit} - -Dito, but split at line breaks. - -CRLF is considered to be one line break. Line breaks are not -included in the resulting list. +Split a Unicode string at line breaks, returning a list of Unicode +strings. CRLF is considered to be one line break. The Line break +characters are not included in the resulting strings. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str, PyObject *table, const char *errors} - Translate a string by applying a character mapping table to it and return the resulting Unicode object. @@ -2556,12 +2519,10 @@ which cause a LookupError) are left untouched and are copied as-is. \var{errors} has the usual meaning for codecs. It may be \NULL{} which indicates to use the default error handling. - \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator, PyObject *seq} - Join a sequence of strings using the given separator and return the resulting Unicode string. \end{cfuncdesc} @@ -2571,7 +2532,6 @@ the resulting Unicode string. int start, int end, int direction} - Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at the given tail end (\var{direction} == -1 means to do a prefix match, \var{direction} == 1 a suffix match), 0 otherwise. @@ -2582,7 +2542,6 @@ the given tail end (\var{direction} == -1 means to do a prefix match, int start, int end, int direction} - Return the first position of \var{substr} in \var{str}[\var{start}:\var{end}] using the given \var{direction} (\var{direction} == 1 means to do a forward search, @@ -2593,7 +2552,6 @@ Return the first position of \var{substr} in PyObject *substr, int start, int end} - Count the number of occurrences of \var{substr} in \var{str}[\var{start}:\var{end}] \end{cfuncdesc} @@ -2602,33 +2560,29 @@ Count the number of occurrences of \var{substr} in PyObject *substr, PyObject *replstr, int maxcount} - Replace at most \var{maxcount} occurrences of \var{substr} in \var{str} with \var{replstr} and return the resulting Unicode object. \var{maxcount} == -1 means: replace all occurrences. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, - PyObject *right} - +\begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right} Compare two strings and return -1, 0, 1 for less than, equal, greater than resp. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format, PyObject *args} -Returns a new string object from \var{format} and \var{args}. Analogous -to \code{\var{format} \% \var{args}}. The \var{args} argument must be -a tuple. +Returns a new string object from \var{format} and \var{args}; this is +analogous to \code{\var{format} \%\ \var{args}}. The +\var{args} argument must be a tuple. \end{cfuncdesc} \begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container, PyObject *element} - Checks whether \var{element} is contained in \var{container} and -returns 1/0 accordingly. +returns true or false accordingly. -\var{element} has to coerce to an one element Unicode string. -1 is +\var{element} has to coerce to a one element Unicode string. \code{-1} is returned in case of an error. \end{cfuncdesc} @@ -2970,7 +2924,7 @@ raised. char *key, PyObject *val} Inserts \var{value} into the dictionary using \var{key} -as a key. \var{key} should be a \ctype{char *}. The key object is +as a key. \var{key} should be a \ctype{char*}. The key object is created using \code{PyString_FromString(\var{key})}. \ttindex{PyString_FromString()} \end{cfuncdesc} @@ -3447,7 +3401,7 @@ Returns true if its argument is a \ctype{PyCObject}. \begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj, void (*destr)(void *)} -Creates a \ctype{PyCObject} from the \code{void *} \var{cobj}. The +Creates a \ctype{PyCObject} from the \code{void *}\var{cobj}. The \var{destr} function will be called when the object is reclaimed, unless it is \NULL. \end{cfuncdesc} |