mirror of
https://github.com/python/cpython
synced 2024-10-04 23:29:39 +00:00
00ee7baf49
which unfortunately means the errors from the bytes type change somewhat: bytes([300]) still raises a ValueError, but bytes([10**100]) now raises a TypeError (either that, or bytes(1.0) also raises a ValueError -- PyNumber_AsSsize_t() can only raise one type of exception.) Merged revisions 51188-51433 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r51189 | kurt.kaiser | 2006-08-10 19:11:09 +0200 (Thu, 10 Aug 2006) | 4 lines Retrieval of previous shell command was not always preserving indentation since 1.2a1) Patch 1528468 Tal Einat. ........ r51190 | guido.van.rossum | 2006-08-10 19:41:07 +0200 (Thu, 10 Aug 2006) | 3 lines Chris McDonough's patch to defend against certain DoS attacks on FieldStorage. SF bug #1112549. ........ r51191 | guido.van.rossum | 2006-08-10 19:42:50 +0200 (Thu, 10 Aug 2006) | 2 lines News item for SF bug 1112549. ........ r51192 | guido.van.rossum | 2006-08-10 20:09:25 +0200 (Thu, 10 Aug 2006) | 2 lines Fix title -- it's rc1, not beta3. ........ r51194 | martin.v.loewis | 2006-08-10 21:04:00 +0200 (Thu, 10 Aug 2006) | 3 lines Update dangling references to the 3.2 database to mention that this is UCD 4.1 now. ........ r51195 | tim.peters | 2006-08-11 00:45:34 +0200 (Fri, 11 Aug 2006) | 6 lines Followup to bug #1069160. PyThreadState_SetAsyncExc(): internal correctness changes wrt refcount safety and deadlock avoidance. Also added a basic test case (relying on ctypes) and repaired the docs. ........ r51196 | tim.peters | 2006-08-11 00:48:45 +0200 (Fri, 11 Aug 2006) | 2 lines Whitespace normalization. ........ r51197 | tim.peters | 2006-08-11 01:22:13 +0200 (Fri, 11 Aug 2006) | 5 lines Whitespace normalization broke test_cgi, because a line of quoted test data relied on preserving a single trailing blank. Changed the string from raw to regular, and forced in the trailing blank via an explicit \x20 escape. ........ r51198 | tim.peters | 2006-08-11 02:49:01 +0200 (Fri, 11 Aug 2006) | 10 lines test_PyThreadState_SetAsyncExc(): This is failing on some 64-bit boxes. I have no idea what the ctypes docs mean by "integers", and blind-guessing here that it intended to mean the signed C "int" type, in which case perhaps I can repair this by feeding the thread id argument to type ctypes.c_long(). Also made the worker thread daemonic, so it doesn't hang Python shutdown if the test continues to fail. ........ r51199 | tim.peters | 2006-08-11 05:49:10 +0200 (Fri, 11 Aug 2006) | 6 lines force_test_exit(): This has been completely ineffective at stopping test_signal from hanging forever on the Tru64 buildbot. That could be because there's no such thing as signal.SIGALARM. Changed to the idiotic (but standard) signal.SIGALRM instead, and added some more debug output. ........ r51202 | neal.norwitz | 2006-08-11 08:09:41 +0200 (Fri, 11 Aug 2006) | 6 lines Fix the failures on cygwin (2006-08-10 fixed the actual locking issue). The first hunk changes the colon to an ! like other Windows variants. We need to always wait on the child so the lock gets released and no other tests fail. This is the try/finally in the second hunk. ........ r51205 | georg.brandl | 2006-08-11 09:15:38 +0200 (Fri, 11 Aug 2006) | 3 lines Add Chris McDonough (latest cgi.py patch) ........ r51206 | georg.brandl | 2006-08-11 09:26:10 +0200 (Fri, 11 Aug 2006) | 3 lines logging's atexit hook now runs even if the rest of the module has already been cleaned up. ........ r51212 | thomas.wouters | 2006-08-11 17:02:39 +0200 (Fri, 11 Aug 2006) | 4 lines Add ignore of *.pyc and *.pyo to Lib/xml/etree/. ........ r51215 | thomas.heller | 2006-08-11 21:55:35 +0200 (Fri, 11 Aug 2006) | 7 lines When a ctypes C callback function is called, zero out the result storage before converting the result to C data. See the comment in the code for details. Provide a better context for errors when the conversion of a callback function's result cannot be converted. ........ r51218 | neal.norwitz | 2006-08-12 03:43:40 +0200 (Sat, 12 Aug 2006) | 6 lines Klocwork made another run and found a bunch more problems. This is the first batch of fixes that should be easy to verify based on context. This fixes problem numbers: 220 (ast), 323-324 (symtable), 321-322 (structseq), 215 (array), 210 (hotshot), 182 (codecs), 209 (etree). ........ r51219 | neal.norwitz | 2006-08-12 03:45:47 +0200 (Sat, 12 Aug 2006) | 9 lines Even though _Py_Mangle() isn't truly public anyone can call it and there was no verification that privateobj was a PyString. If it wasn't a string, this could have allowed a NULL pointer to creep in below and crash. I wonder if this should be PyString_CheckExact? Must identifiers be strings or can they be subclasses? Klocwork #275 ........ r51220 | neal.norwitz | 2006-08-12 03:46:42 +0200 (Sat, 12 Aug 2006) | 5 lines It's highly unlikely, though possible for PyEval_Get*() to return NULLs. So be safe and do an XINCREF. Klocwork # 221-222. ........ r51221 | neal.norwitz | 2006-08-12 03:47:59 +0200 (Sat, 12 Aug 2006) | 7 lines This code is actually not used unless WITHOUT_COMPLEX is defined. However, there was no error checking that PyFloat_FromDouble returned a valid pointer. I believe this change is correct as it seemed to follow other code in the area. Klocwork # 292. ........ r51222 | neal.norwitz | 2006-08-12 03:49:12 +0200 (Sat, 12 Aug 2006) | 5 lines Handle NULL nodes while parsing. I'm not entirely sure this is correct. There might be something else that needs to be done to setup the error. Klocwork #295. ........ r51223 | neal.norwitz | 2006-08-12 03:50:38 +0200 (Sat, 12 Aug 2006) | 6 lines If _stat_float_times is false, we will try to INCREF ival which could be NULL. Return early in that case. The caller checks for PyErr_Occurred so this should be ok. Klocwork #297 ........ r51224 | neal.norwitz | 2006-08-12 03:51:12 +0200 (Sat, 12 Aug 2006) | 3 lines Move the assert which checks for a NULL pointer first. Klocwork #274. ........ r51225 | neal.norwitz | 2006-08-12 03:53:28 +0200 (Sat, 12 Aug 2006) | 5 lines Try to handle a malloc failure. I'm not entirely sure this is correct. There might be something else we need to do to handle the exception. Klocwork # 212-213 ........ r51226 | neal.norwitz | 2006-08-12 03:57:47 +0200 (Sat, 12 Aug 2006) | 6 lines I'm not sure why this code allocates this string for the error message. I think it would be better to always use snprintf and have the format limit the size of the name appropriately (like %.200s). Klocwork #340 ........ r51227 | neal.norwitz | 2006-08-12 04:06:34 +0200 (Sat, 12 Aug 2006) | 3 lines Check returned pointer is valid. Klocwork #233 ........ r51228 | neal.norwitz | 2006-08-12 04:12:30 +0200 (Sat, 12 Aug 2006) | 1 line Whoops, how did that get in there. :-) Revert all the parts of 51227 that were not supposed to go it. Only Modules/_ctypes/cfields.c was supposed to be changed ........ r51229 | neal.norwitz | 2006-08-12 04:33:36 +0200 (Sat, 12 Aug 2006) | 4 lines Don't deref v if it's NULL. Klocwork #214 ........ r51230 | neal.norwitz | 2006-08-12 05:16:54 +0200 (Sat, 12 Aug 2006) | 5 lines Check return of PyMem_MALLOC (garbage) is non-NULL. Check seq in both portions of if/else. Klocwork #289-290. ........ r51231 | neal.norwitz | 2006-08-12 05:17:41 +0200 (Sat, 12 Aug 2006) | 4 lines PyModule_GetDict() can fail, produce fatal errors if this happens on startup. Klocwork #298-299. ........ r51232 | neal.norwitz | 2006-08-12 05:18:50 +0200 (Sat, 12 Aug 2006) | 5 lines Verify verdat which is returned from malloc is not NULL. Ensure we don't pass NULL to free. Klocwork #306 (at least the first part, checking malloc) ........ r51233 | tim.peters | 2006-08-12 06:42:47 +0200 (Sat, 12 Aug 2006) | 35 lines test_signal: Signal handling on the Tru64 buildbot appears to be utterly insane. Plug some theoretical insecurities in the test script: - Verify that the SIGALRM handler was actually installed. - Don't call alarm() before the handler is installed. - Move everything that can fail inside the try/finally, so the test cleans up after itself more often. - Try sending all the expected signals in force_test_exit(), not just SIGALRM. Since that was fixed to actually send SIGALRM (instead of invisibly dying with an AttributeError), we've seen that sending SIGALRM alone does not stop this from hanging. - Move the "kill the child" business into the finally clause, so the child doesn't survive test failure to send SIGALRM to other tests later (there are also baffling SIGALRM-related failures in test_socket). - Cancel the alarm in the finally clause -- if the test dies early, we again don't want SIGALRM showing up to confuse a later test. Alas, this still relies on timing luck wrt the spawned script that sends the test signals, but it's hard to see how waiting for seconds can so often be so unlucky. test_threadedsignals: curiously, this test never fails on Tru64, but doesn't normally signal SIGALRM. Anyway, fixed an obvious (but probably inconsequential) logic error. ........ r51234 | tim.peters | 2006-08-12 07:17:41 +0200 (Sat, 12 Aug 2006) | 8 lines Ah, fudge. One of the prints here actually "shouldn't be" protected by "if verbose:", which caused the test to fail on all non-Windows boxes. Note that I deliberately didn't convert this to unittest yet, because I expect it would be even harder to debug this on Tru64 after conversion. ........ r51235 | georg.brandl | 2006-08-12 10:32:02 +0200 (Sat, 12 Aug 2006) | 3 lines Repair logging test spew caused by rev. 51206. ........ r51236 | neal.norwitz | 2006-08-12 19:03:09 +0200 (Sat, 12 Aug 2006) | 8 lines Patch #1538606, Patch to fix __index__() clipping. I modified this patch some by fixing style, some error checking, and adding XXX comments. This patch requires review and some changes are to be expected. I'm checking in now to get the greatest possible review and establish a baseline for moving forward. I don't want this to hold up release if possible. ........ r51238 | neal.norwitz | 2006-08-12 20:44:06 +0200 (Sat, 12 Aug 2006) | 10 lines Fix a couple of bugs exposed by the new __index__ code. The 64-bit buildbots were failing due to inappropriate clipping of numbers larger than 2**31 with new-style classes. (typeobject.c) In reviewing the code for classic classes, there were 2 problems. Any negative value return could be returned. Always return -1 if there was an error. Also make the checks similar with the new-style classes. I believe this is correct for 32 and 64 bit boxes, including Windows64. Add a test of classic classes too. ........ r51240 | neal.norwitz | 2006-08-13 02:20:49 +0200 (Sun, 13 Aug 2006) | 1 line SF bug #1539336, distutils example code missing ........ r51245 | neal.norwitz | 2006-08-13 20:10:10 +0200 (Sun, 13 Aug 2006) | 6 lines Move/copy assert for tstate != NULL before first use. Verify that PyEval_Get{Globals,Locals} returned valid pointers. Klocwork 231-232 ........ r51246 | neal.norwitz | 2006-08-13 20:10:28 +0200 (Sun, 13 Aug 2006) | 5 lines Handle a whole lot of failures from PyString_FromInternedString(). Should fix most of Klocwork 234-272. ........ r51247 | neal.norwitz | 2006-08-13 20:10:47 +0200 (Sun, 13 Aug 2006) | 8 lines cpathname could be NULL if it was longer than MAXPATHLEN. Don't try to write the .pyc to NULL. Check results of PyList_GetItem() and PyModule_GetDict() are not NULL. Klocwork 282, 283, 285 ........ r51248 | neal.norwitz | 2006-08-13 20:11:08 +0200 (Sun, 13 Aug 2006) | 6 lines Fix segfault when doing string formatting on subclasses of long if __oct__, __hex__ don't return a string. Klocwork 308 ........ r51250 | neal.norwitz | 2006-08-13 20:11:27 +0200 (Sun, 13 Aug 2006) | 5 lines Check return result of PyModule_GetDict(). Fix a bunch of refleaks in the init of the module. This would only be found when running python -v. ........ r51251 | neal.norwitz | 2006-08-13 20:11:43 +0200 (Sun, 13 Aug 2006) | 5 lines Handle malloc and fopen failures more gracefully. Klocwork 180-181 ........ r51252 | neal.norwitz | 2006-08-13 20:12:03 +0200 (Sun, 13 Aug 2006) | 7 lines It's very unlikely, though possible that source is not a string. Verify that PyString_AsString() returns a valid pointer. (The problem can arise when zlib.decompress doesn't return a string.) Klocwork 346 ........ r51253 | neal.norwitz | 2006-08-13 20:12:26 +0200 (Sun, 13 Aug 2006) | 5 lines Handle failures from lookup. Klocwork 341-342 ........ r51254 | neal.norwitz | 2006-08-13 20:12:45 +0200 (Sun, 13 Aug 2006) | 6 lines Handle failure from PyModule_GetDict() (Klocwork 208). Fix a bunch of refleaks in the init of the module. This would only be found when running python -v. ........ r51255 | neal.norwitz | 2006-08-13 20:13:02 +0200 (Sun, 13 Aug 2006) | 4 lines Really address the issue of where to place the assert for leftblock. (Followup of Klocwork 274) ........ r51256 | neal.norwitz | 2006-08-13 20:13:36 +0200 (Sun, 13 Aug 2006) | 4 lines Handle malloc failure. Klocwork 281 ........ r51258 | neal.norwitz | 2006-08-13 20:40:39 +0200 (Sun, 13 Aug 2006) | 4 lines Handle alloca failures. Klocwork 225-228 ........ r51259 | neal.norwitz | 2006-08-13 20:41:15 +0200 (Sun, 13 Aug 2006) | 1 line Get rid of compiler warning ........ r51261 | neal.norwitz | 2006-08-14 02:51:15 +0200 (Mon, 14 Aug 2006) | 1 line Ignore pgen.exe and kill_python.exe for cygwin ........ r51262 | neal.norwitz | 2006-08-14 02:59:03 +0200 (Mon, 14 Aug 2006) | 4 lines Can't return NULL from a void function. If there is a memory error, about the best we can do is call PyErr_WriteUnraisable and go on. We won't be able to do the call below either, so verify delstr is valid. ........ r51263 | neal.norwitz | 2006-08-14 03:49:54 +0200 (Mon, 14 Aug 2006) | 1 line Update purify doc some. ........ r51264 | thomas.heller | 2006-08-14 09:13:05 +0200 (Mon, 14 Aug 2006) | 2 lines Remove unused, buggy test function. Fixes klockwork issue #207. ........ r51265 | thomas.heller | 2006-08-14 09:14:09 +0200 (Mon, 14 Aug 2006) | 2 lines Check for NULL return value from new_CArgObject(). Fixes klockwork issues #183, #184, #185. ........ r51266 | thomas.heller | 2006-08-14 09:50:14 +0200 (Mon, 14 Aug 2006) | 2 lines Check for NULL return value of GenericCData_new(). Fixes klockwork issues #188, #189. ........ r51274 | thomas.heller | 2006-08-14 12:02:24 +0200 (Mon, 14 Aug 2006) | 2 lines Revert the change that tries to zero out a closure's result storage area because the size if unknown in source/callproc.c. ........ r51276 | marc-andre.lemburg | 2006-08-14 12:55:19 +0200 (Mon, 14 Aug 2006) | 11 lines Slightly revised version of patch #1538956: Replace UnicodeDecodeErrors raised during == and != compares of Unicode and other objects with a new UnicodeWarning. All other comparisons continue to raise exceptions. Exceptions other than UnicodeDecodeErrors are also left untouched. ........ r51277 | thomas.heller | 2006-08-14 13:17:48 +0200 (Mon, 14 Aug 2006) | 13 lines Apply the patch #1532975 plus ideas from the patch #1533481. ctypes instances no longer have the internal and undocumented '_as_parameter_' attribute which was used to adapt them to foreign function calls; this mechanism is replaced by a function pointer in the type's stgdict. In the 'from_param' class methods, try the _as_parameter_ attribute if other conversions are not possible. This makes the documented _as_parameter_ mechanism work as intended. Change the ctypes version number to 1.0.1. ........ r51278 | marc-andre.lemburg | 2006-08-14 13:44:34 +0200 (Mon, 14 Aug 2006) | 3 lines Readd NEWS items that were accidentally removed by r51276. ........ r51279 | georg.brandl | 2006-08-14 14:36:06 +0200 (Mon, 14 Aug 2006) | 3 lines Improve markup in PyUnicode_RichCompare. ........ r51280 | marc-andre.lemburg | 2006-08-14 14:57:27 +0200 (Mon, 14 Aug 2006) | 3 lines Correct an accidentally removed previous patch. ........ r51281 | thomas.heller | 2006-08-14 18:17:41 +0200 (Mon, 14 Aug 2006) | 3 lines Patch #1536908: Add support for AMD64 / OpenBSD. Remove the -no-stack-protector compiler flag for OpenBSD as it has been reported to be unneeded. ........ r51282 | thomas.heller | 2006-08-14 18:20:04 +0200 (Mon, 14 Aug 2006) | 1 line News item for rev 51281. ........ r51283 | georg.brandl | 2006-08-14 22:25:39 +0200 (Mon, 14 Aug 2006) | 3 lines Fix refleak introduced in rev. 51248. ........ r51284 | georg.brandl | 2006-08-14 23:34:08 +0200 (Mon, 14 Aug 2006) | 5 lines Make tabnanny recognize IndentationErrors raised by tokenize. Add a test to test_inspect to make sure indented source is recognized correctly. (fixes #1224621) ........ r51285 | georg.brandl | 2006-08-14 23:42:55 +0200 (Mon, 14 Aug 2006) | 3 lines Patch #1535500: fix segfault in BZ2File.writelines and make sure it raises the correct exceptions. ........ r51287 | georg.brandl | 2006-08-14 23:45:32 +0200 (Mon, 14 Aug 2006) | 3 lines Add an additional test: BZ2File write methods should raise IOError when file is read-only. ........ r51289 | georg.brandl | 2006-08-14 23:55:28 +0200 (Mon, 14 Aug 2006) | 3 lines Patch #1536071: trace.py should now find the full module name of a file correctly even on Windows. ........ r51290 | georg.brandl | 2006-08-15 00:01:24 +0200 (Tue, 15 Aug 2006) | 3 lines Cookie.py shouldn't "bogusly" use string._idmap. ........ r51291 | georg.brandl | 2006-08-15 00:10:24 +0200 (Tue, 15 Aug 2006) | 3 lines Patch #1511317: don't crash on invalid hostname info ........ r51292 | tim.peters | 2006-08-15 02:25:04 +0200 (Tue, 15 Aug 2006) | 2 lines Whitespace normalization. ........ r51293 | neal.norwitz | 2006-08-15 06:14:57 +0200 (Tue, 15 Aug 2006) | 3 lines Georg fixed one of my bugs, so I'll repay him with 2 NEWS entries. Now we're even. :-) ........ r51295 | neal.norwitz | 2006-08-15 06:58:28 +0200 (Tue, 15 Aug 2006) | 8 lines Fix the test for SocketServer so it should pass on cygwin and not fail sporadically on other platforms. This is really a band-aid that doesn't fix the underlying issue in SocketServer. It's not clear if it's worth it to fix SocketServer, however, I opened a bug to track it: http://python.org/sf/1540386 ........ r51296 | neal.norwitz | 2006-08-15 06:59:30 +0200 (Tue, 15 Aug 2006) | 3 lines Update the docstring to use a version a little newer than 1999. This was taken from a Debian patch. Should we update the version for each release? ........ r51298 | neal.norwitz | 2006-08-15 08:29:03 +0200 (Tue, 15 Aug 2006) | 2 lines Subclasses of int/long are allowed to define an __index__. ........ r51300 | thomas.heller | 2006-08-15 15:07:21 +0200 (Tue, 15 Aug 2006) | 1 line Check for NULL return value from new_CArgObject calls. ........ r51303 | kurt.kaiser | 2006-08-16 05:15:26 +0200 (Wed, 16 Aug 2006) | 2 lines The 'with' statement is now a Code Context block opener ........ r51304 | anthony.baxter | 2006-08-16 05:42:26 +0200 (Wed, 16 Aug 2006) | 1 line preparing for 2.5c1 ........ r51305 | anthony.baxter | 2006-08-16 05:58:37 +0200 (Wed, 16 Aug 2006) | 1 line preparing for 2.5c1 - no, really this time ........ r51306 | kurt.kaiser | 2006-08-16 07:01:42 +0200 (Wed, 16 Aug 2006) | 9 lines Patch #1540892: site.py Quitter() class attempts to close sys.stdin before raising SystemExit, allowing IDLE to honor quit() and exit(). M Lib/site.py M Lib/idlelib/PyShell.py M Lib/idlelib/CREDITS.txt M Lib/idlelib/NEWS.txt M Misc/NEWS ........ r51307 | ka-ping.yee | 2006-08-16 09:02:50 +0200 (Wed, 16 Aug 2006) | 6 lines Update code and tests to support the 'bytes_le' attribute (for little-endian byte order on Windows), and to work around clocks with low resolution yielding duplicate UUIDs. Anthony Baxter has approved this change. ........ r51308 | kurt.kaiser | 2006-08-16 09:04:17 +0200 (Wed, 16 Aug 2006) | 2 lines Get quit() and exit() to work cleanly when not using subprocess. ........ r51309 | marc-andre.lemburg | 2006-08-16 10:13:26 +0200 (Wed, 16 Aug 2006) | 2 lines Revert to having static version numbers again. ........ r51310 | martin.v.loewis | 2006-08-16 14:55:10 +0200 (Wed, 16 Aug 2006) | 2 lines Build _hashlib on Windows. Build OpenSSL with masm assembler code. Fixes #1535502. ........ r51311 | thomas.heller | 2006-08-16 15:03:11 +0200 (Wed, 16 Aug 2006) | 6 lines Add commented assert statements to check that the result of PyObject_stgdict() and PyType_stgdict() calls are non-NULL before dereferencing the result. Hopefully this fixes what klocwork is complaining about. Fix a few other nits as well. ........ r51312 | anthony.baxter | 2006-08-16 15:08:25 +0200 (Wed, 16 Aug 2006) | 1 line news entry for 51307 ........ r51313 | andrew.kuchling | 2006-08-16 15:22:20 +0200 (Wed, 16 Aug 2006) | 1 line Add UnicodeWarning ........ r51314 | andrew.kuchling | 2006-08-16 15:41:52 +0200 (Wed, 16 Aug 2006) | 1 line Bump document version to 1.0; remove pystone paragraph ........ r51315 | andrew.kuchling | 2006-08-16 15:51:32 +0200 (Wed, 16 Aug 2006) | 1 line Link to docs; remove an XXX comment ........ r51316 | martin.v.loewis | 2006-08-16 15:58:51 +0200 (Wed, 16 Aug 2006) | 1 line Make cl build step compile-only (/c). Remove libs from source list. ........ r51317 | thomas.heller | 2006-08-16 16:07:44 +0200 (Wed, 16 Aug 2006) | 5 lines The __repr__ method of a NULL py_object does no longer raise an exception. Remove a stray '?' character from the exception text when the value is retrieved of such an object. Includes tests. ........ r51318 | andrew.kuchling | 2006-08-16 16:18:23 +0200 (Wed, 16 Aug 2006) | 1 line Update bug/patch counts ........ r51319 | andrew.kuchling | 2006-08-16 16:21:14 +0200 (Wed, 16 Aug 2006) | 1 line Wording/typo fixes ........ r51320 | thomas.heller | 2006-08-16 17:10:12 +0200 (Wed, 16 Aug 2006) | 9 lines Remove the special casing of Py_None when converting the return value of the Python part of a callback function to C. If it cannot be converted, call PyErr_WriteUnraisable with the exception we got. Before, arbitrary data has been passed to the calling C code in this case. (I'm not really sure the NEWS entry is understandable, but I cannot find better words) ........ r51321 | marc-andre.lemburg | 2006-08-16 18:11:01 +0200 (Wed, 16 Aug 2006) | 2 lines Add NEWS item mentioning the reverted distutils version number patch. ........ r51322 | fredrik.lundh | 2006-08-16 18:47:07 +0200 (Wed, 16 Aug 2006) | 5 lines SF#1534630 ignore data that arrives before the opening start tag ........ r51324 | andrew.kuchling | 2006-08-16 19:11:18 +0200 (Wed, 16 Aug 2006) | 1 line Grammar fix ........ r51328 | thomas.heller | 2006-08-16 20:02:11 +0200 (Wed, 16 Aug 2006) | 12 lines Tutorial: Clarify somewhat how parameters are passed to functions (especially explain what integer means). Correct the table - Python integers and longs can both be used. Further clarification to the table comparing ctypes types, Python types, and C types. Reference: Replace integer by C ``int`` where it makes sense. ........ r51329 | kurt.kaiser | 2006-08-16 23:45:59 +0200 (Wed, 16 Aug 2006) | 8 lines File menu hotkeys: there were three 'p' assignments. Reassign the 'Save Copy As' and 'Print' hotkeys to 'y' and 't'. Change the Shell menu hotkey from 's' to 'l'. M Bindings.py M PyShell.py M NEWS.txt ........ r51330 | neil.schemenauer | 2006-08-17 01:38:05 +0200 (Thu, 17 Aug 2006) | 3 lines Fix a bug in the ``compiler`` package that caused invalid code to be generated for generator expressions. ........ r51342 | martin.v.loewis | 2006-08-17 21:19:32 +0200 (Thu, 17 Aug 2006) | 3 lines Merge 51340 and 51341 from 2.5 branch: Leave tk build directory to restore original path. Invoke debug mk1mf.pl after running Configure. ........ r51354 | martin.v.loewis | 2006-08-18 05:47:18 +0200 (Fri, 18 Aug 2006) | 3 lines Bug #1541863: uuid.uuid1 failed to generate unique identifiers on systems with low clock resolution. ........ r51355 | neal.norwitz | 2006-08-18 05:57:54 +0200 (Fri, 18 Aug 2006) | 1 line Add template for 2.6 on HEAD ........ r51356 | neal.norwitz | 2006-08-18 06:01:38 +0200 (Fri, 18 Aug 2006) | 1 line More post-release wibble ........ r51357 | neal.norwitz | 2006-08-18 06:58:33 +0200 (Fri, 18 Aug 2006) | 1 line Try to get Windows bots working again ........ r51358 | neal.norwitz | 2006-08-18 07:10:00 +0200 (Fri, 18 Aug 2006) | 1 line Try to get Windows bots working again. Take 2 ........ r51359 | neal.norwitz | 2006-08-18 07:39:20 +0200 (Fri, 18 Aug 2006) | 1 line Try to get Unix bots install working again. ........ r51360 | neal.norwitz | 2006-08-18 07:41:46 +0200 (Fri, 18 Aug 2006) | 1 line Set version to 2.6a0, seems more consistent. ........ r51362 | neal.norwitz | 2006-08-18 08:14:52 +0200 (Fri, 18 Aug 2006) | 1 line More version wibble ........ r51364 | georg.brandl | 2006-08-18 09:27:59 +0200 (Fri, 18 Aug 2006) | 4 lines Bug #1541682: Fix example in the "Refcount details" API docs. Additionally, remove a faulty example showing PySequence_SetItem applied to a newly created list object and add notes that this isn't a good idea. ........ r51366 | anthony.baxter | 2006-08-18 09:29:02 +0200 (Fri, 18 Aug 2006) | 3 lines Updating IDLE's version number to match Python's (as per python-dev discussion). ........ r51367 | anthony.baxter | 2006-08-18 09:30:07 +0200 (Fri, 18 Aug 2006) | 1 line RPM specfile updates ........ r51368 | georg.brandl | 2006-08-18 09:35:47 +0200 (Fri, 18 Aug 2006) | 2 lines Typo in tp_clear docs. ........ r51378 | andrew.kuchling | 2006-08-18 15:57:13 +0200 (Fri, 18 Aug 2006) | 1 line Minor edits ........ r51379 | thomas.heller | 2006-08-18 16:38:46 +0200 (Fri, 18 Aug 2006) | 6 lines Add asserts to check for 'impossible' NULL values, with comments. In one place where I'n not 1000% sure about the non-NULL, raise a RuntimeError for safety. This should fix the klocwork issues that Neal sent me. If so, it should be applied to the release25-maint branch also. ........ r51400 | neal.norwitz | 2006-08-19 06:22:33 +0200 (Sat, 19 Aug 2006) | 5 lines Move initialization of interned strings to before allocating the object so we don't leak op. (Fixes an earlier patch to this code) Klockwork #350 ........ r51401 | neal.norwitz | 2006-08-19 06:23:04 +0200 (Sat, 19 Aug 2006) | 4 lines Move assert to after NULL check, otherwise we deref NULL in the assert. Klocwork #307 ........ r51402 | neal.norwitz | 2006-08-19 06:25:29 +0200 (Sat, 19 Aug 2006) | 2 lines SF #1542693: Remove semi-colon at end of PyImport_ImportModuleEx macro ........ r51403 | neal.norwitz | 2006-08-19 06:28:55 +0200 (Sat, 19 Aug 2006) | 6 lines Move initialization to after the asserts for non-NULL values. Klocwork 286-287. (I'm not backporting this, but if someone wants to, feel free.) ........ r51404 | neal.norwitz | 2006-08-19 06:52:03 +0200 (Sat, 19 Aug 2006) | 6 lines Handle PyString_FromInternedString() failing (unlikely, but possible). Klocwork #325 (I'm not backporting this, but if someone wants to, feel free.) ........ r51416 | georg.brandl | 2006-08-20 15:15:39 +0200 (Sun, 20 Aug 2006) | 2 lines Patch #1542948: fix urllib2 header casing issue. With new test. ........ r51428 | jeremy.hylton | 2006-08-21 18:19:37 +0200 (Mon, 21 Aug 2006) | 3 lines Move peephole optimizer to separate file. ........ r51429 | jeremy.hylton | 2006-08-21 18:20:29 +0200 (Mon, 21 Aug 2006) | 2 lines Move peephole optimizer to separate file. (Forgot .h in previous checkin.) ........ r51432 | neal.norwitz | 2006-08-21 19:59:46 +0200 (Mon, 21 Aug 2006) | 5 lines Fix bug #1543303, tarfile adds padding that breaks gunzip. Patch # 1543897. Will backport to 2.5 ........ r51433 | neal.norwitz | 2006-08-21 20:01:30 +0200 (Mon, 21 Aug 2006) | 2 lines Add assert to make Klocwork happy (#276) ........
3204 lines
130 KiB
TeX
3204 lines
130 KiB
TeX
\chapter{Concrete Objects Layer \label{concrete}}
|
|
|
|
|
|
The functions in this chapter are specific to certain Python object
|
|
types. Passing them an object of the wrong type is not a good idea;
|
|
if you receive an object from a Python program and you are not sure
|
|
that it has the right type, you must perform a type check first;
|
|
for example, to check that an object is a dictionary, use
|
|
\cfunction{PyDict_Check()}. The chapter is structured like the
|
|
``family tree'' of Python object types.
|
|
|
|
\warning{While the functions described in this chapter carefully check
|
|
the type of the objects which are passed in, many of them do not check
|
|
for \NULL{} being passed instead of a valid object. Allowing \NULL{}
|
|
to be passed in can cause memory access violations and immediate
|
|
termination of the interpreter.}
|
|
|
|
|
|
\section{Fundamental Objects \label{fundamental}}
|
|
|
|
This section describes Python type objects and the singleton object
|
|
\code{None}.
|
|
|
|
|
|
\subsection{Type Objects \label{typeObjects}}
|
|
|
|
\obindex{type}
|
|
\begin{ctypedesc}{PyTypeObject}
|
|
The C structure of the objects used to describe built-in types.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyObject*}{PyType_Type}
|
|
This is the type object for type objects; it is the same object as
|
|
\code{type} and \code{types.TypeType} in the Python layer.
|
|
\withsubitem{(in module types)}{\ttindex{TypeType}}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyType_Check}{PyObject *o}
|
|
Return true if the object \var{o} is a type object, including
|
|
instances of types derived from the standard type object. Return
|
|
false in all other cases.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyType_CheckExact}{PyObject *o}
|
|
Return true if the object \var{o} is a type object, but not a
|
|
subtype of the standard type object. Return false in all other
|
|
cases.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature}
|
|
Return true if the type object \var{o} sets the feature
|
|
\var{feature}. Type features are denoted by single bit flags.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyType_IS_GC}{PyObject *o}
|
|
Return true if the type object includes support for the cycle
|
|
detector; this tests the type flag \constant{Py_TPFLAGS_HAVE_GC}.
|
|
\versionadded{2.0}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b}
|
|
Return true if \var{a} is a subtype of \var{b}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type,
|
|
Py_ssize_t nitems}
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyType_GenericNew}{PyTypeObject *type,
|
|
PyObject *args, PyObject *kwds}
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyType_Ready}{PyTypeObject *type}
|
|
Finalize a type object. This should be called on all type objects
|
|
to finish their initialization. This function is responsible for
|
|
adding inherited slots from a type's base class. Return \code{0}
|
|
on success, or return \code{-1} and sets an exception on error.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{The None Object \label{noneObject}}
|
|
|
|
\obindex{None}
|
|
Note that the \ctype{PyTypeObject} for \code{None} is not directly
|
|
exposed in the Python/C API. Since \code{None} is a singleton,
|
|
testing for object identity (using \samp{==} in C) is sufficient.
|
|
There is no \cfunction{PyNone_Check()} function for the same reason.
|
|
|
|
\begin{cvardesc}{PyObject*}{Py_None}
|
|
The Python \code{None} object, denoting lack of value. This object
|
|
has no methods. It needs to be treated just like any other object
|
|
with respect to reference counts.
|
|
\end{cvardesc}
|
|
|
|
\begin{csimplemacrodesc}{Py_RETURN_NONE}
|
|
Properly handle returning \cdata{Py_None} from within a C function.
|
|
\end{csimplemacrodesc}
|
|
|
|
|
|
\section{Numeric Objects \label{numericObjects}}
|
|
|
|
\obindex{numeric}
|
|
|
|
|
|
\subsection{Plain Integer Objects \label{intObjects}}
|
|
|
|
\obindex{integer}
|
|
\begin{ctypedesc}{PyIntObject}
|
|
This subtype of \ctype{PyObject} represents a Python integer
|
|
object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyInt_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python plain
|
|
integer type. This is the same object as \code{int} and
|
|
\code{types.IntType}.
|
|
\withsubitem{(in modules types)}{\ttindex{IntType}}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *o}
|
|
Return true if \var{o} is of type \cdata{PyInt_Type} or a subtype
|
|
of \cdata{PyInt_Type}.
|
|
\versionchanged[Allowed subtypes to be accepted]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject *o}
|
|
Return true if \var{o} is of type \cdata{PyInt_Type}, but not a
|
|
subtype of \cdata{PyInt_Type}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyInt_FromString}{char *str, char **pend,
|
|
int base}
|
|
Return a new \ctype{PyIntObject} or \ctype{PyLongObject} based on the
|
|
string value in \var{str}, which is interpreted according to the radix in
|
|
\var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will point to
|
|
the first character in \var{str} which follows the representation of the
|
|
number. If \var{base} is \code{0}, the radix will be determined based on
|
|
the leading characters of \var{str}: if \var{str} starts with \code{'0x'}
|
|
or \code{'0X'}, radix 16 will be used; if \var{str} starts with
|
|
\code{'0'}, radix 8 will be used; otherwise radix 10 will be used. If
|
|
\var{base} is not \code{0}, it must be between \code{2} and \code{36},
|
|
inclusive. Leading spaces are ignored. If there are no digits,
|
|
\exception{ValueError} will be raised. If the string represents a number
|
|
too large to be contained within the machine's \ctype{long int} type and
|
|
overflow warnings are being suppressed, a \ctype{PyLongObject} will be
|
|
returned. If overflow warnings are not being suppressed, \NULL{} will be
|
|
returned in this case.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
|
|
Create a new integer object with a value of \var{ival}.
|
|
|
|
The current implementation keeps an array of integer objects for all
|
|
integers between \code{-5} and \code{256}, when you create an int in
|
|
that range you actually just get back a reference to the existing
|
|
object. So it should be possible to change the value of \code{1}. I
|
|
suspect the behaviour of Python in this case is undefined. :-)
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyInt_FromSsize_t}{Py_ssize_t ival}
|
|
Create a new integer object with a value of \var{ival}.
|
|
If the value exceeds \code{LONG_MAX}, a long integer object is
|
|
returned.
|
|
|
|
\versionadded{2.5}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
|
|
Will first attempt to cast the object to a \ctype{PyIntObject}, if
|
|
it is not already one, and then return its value. If there is an
|
|
error, \code{-1} is returned, and the caller should check
|
|
\code{PyErr_Occurred()} to find out whether there was an error, or
|
|
whether the value just happened to be -1.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
|
|
Return the value of the object \var{io}. No error checking is
|
|
performed.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{unsigned long}{PyInt_AsUnsignedLongMask}{PyObject *io}
|
|
Will first attempt to cast the object to a \ctype{PyIntObject} or
|
|
\ctype{PyLongObject}, if it is not already one, and then return its
|
|
value as unsigned long. This function does not check for overflow.
|
|
\versionadded{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyInt_AsUnsignedLongLongMask}{PyObject *io}
|
|
Will first attempt to cast the object to a \ctype{PyIntObject} or
|
|
\ctype{PyLongObject}, if it is not already one, and then return its
|
|
value as unsigned long long, without checking for overflow.
|
|
\versionadded{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyInt_AsSsize_t}{PyObject *io}
|
|
Will first attempt to cast the object to a \ctype{PyIntObject} or
|
|
\ctype{PyLongObject}, if it is not already one, and then return its
|
|
value as \ctype{Py_ssize_t}.
|
|
\versionadded{2.5}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyInt_GetMax}{}
|
|
Return the system's idea of the largest integer it can handle
|
|
(\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system
|
|
header files).
|
|
\end{cfuncdesc}
|
|
|
|
\subsection{Boolean Objects \label{boolObjects}}
|
|
|
|
Booleans in Python are implemented as a subclass of integers. There
|
|
are only two booleans, \constant{Py_False} and \constant{Py_True}. As
|
|
such, the normal creation and deletion functions don't apply to
|
|
booleans. The following macros are available, however.
|
|
|
|
\begin{cfuncdesc}{int}{PyBool_Check}{PyObject *o}
|
|
Return true if \var{o} is of type \cdata{PyBool_Type}.
|
|
\versionadded{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cvardesc}{PyObject*}{Py_False}
|
|
The Python \code{False} object. This object has no methods. It needs to
|
|
be treated just like any other object with respect to reference counts.
|
|
\end{cvardesc}
|
|
|
|
\begin{cvardesc}{PyObject*}{Py_True}
|
|
The Python \code{True} object. This object has no methods. It needs to
|
|
be treated just like any other object with respect to reference counts.
|
|
\end{cvardesc}
|
|
|
|
\begin{csimplemacrodesc}{Py_RETURN_FALSE}
|
|
Return \constant{Py_False} from a function, properly incrementing its
|
|
reference count.
|
|
\versionadded{2.4}
|
|
\end{csimplemacrodesc}
|
|
|
|
\begin{csimplemacrodesc}{Py_RETURN_TRUE}
|
|
Return \constant{Py_True} from a function, properly incrementing its
|
|
reference count.
|
|
\versionadded{2.4}
|
|
\end{csimplemacrodesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyBool_FromLong}{long v}
|
|
Return a new reference to \constant{Py_True} or \constant{Py_False}
|
|
depending on the truth value of \var{v}.
|
|
\versionadded{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
\subsection{Long Integer Objects \label{longObjects}}
|
|
|
|
\obindex{long integer}
|
|
\begin{ctypedesc}{PyLongObject}
|
|
This subtype of \ctype{PyObject} represents a Python long integer
|
|
object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyLong_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python long
|
|
integer type. This is the same object as \code{long} and
|
|
\code{types.LongType}.
|
|
\withsubitem{(in modules types)}{\ttindex{LongType}}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
|
|
Return true if its argument is a \ctype{PyLongObject} or a subtype
|
|
of \ctype{PyLongObject}.
|
|
\versionchanged[Allowed subtypes to be accepted]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p}
|
|
Return true if its argument is a \ctype{PyLongObject}, but not a
|
|
subtype of \ctype{PyLongObject}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
|
|
Return a new \ctype{PyLongObject} object from \var{v}, or \NULL{}
|
|
on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
|
|
Return a new \ctype{PyLongObject} object from a C \ctype{unsigned
|
|
long}, or \NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{PY_LONG_LONG v}
|
|
Return a new \ctype{PyLongObject} object from a C \ctype{long long},
|
|
or \NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned PY_LONG_LONG v}
|
|
Return a new \ctype{PyLongObject} object from a C \ctype{unsigned
|
|
long long}, or \NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
|
|
Return a new \ctype{PyLongObject} object from the integer part of
|
|
\var{v}, or \NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
|
|
int base}
|
|
Return a new \ctype{PyLongObject} based on the string value in
|
|
\var{str}, which is interpreted according to the radix in
|
|
\var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will
|
|
point to the first character in \var{str} which follows the
|
|
representation of the number. If \var{base} is \code{0}, the radix
|
|
will be determined based on the leading characters of \var{str}: if
|
|
\var{str} starts with \code{'0x'} or \code{'0X'}, radix 16 will be
|
|
used; if \var{str} starts with \code{'0'}, radix 8 will be used;
|
|
otherwise radix 10 will be used. If \var{base} is not \code{0}, it
|
|
must be between \code{2} and \code{36}, inclusive. Leading spaces
|
|
are ignored. If there are no digits, \exception{ValueError} will be
|
|
raised.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u,
|
|
Py_ssize_t length, int base}
|
|
Convert a sequence of Unicode digits to a Python long integer
|
|
value. The first parameter, \var{u}, points to the first character
|
|
of the Unicode string, \var{length} gives the number of characters,
|
|
and \var{base} is the radix for the conversion. The radix must be
|
|
in the range [2, 36]; if it is out of range, \exception{ValueError}
|
|
will be raised.
|
|
\versionadded{1.6}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p}
|
|
Create a Python integer or long integer from the pointer \var{p}.
|
|
The pointer value can be retrieved from the resulting value using
|
|
\cfunction{PyLong_AsVoidPtr()}.
|
|
\versionadded{1.5.2}
|
|
\versionchanged[If the integer is larger than LONG_MAX,
|
|
a positive long integer is returned]{2.5}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
|
|
Return a C \ctype{long} representation of the contents of
|
|
\var{pylong}. If \var{pylong} is greater than
|
|
\constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError}
|
|
is raised.
|
|
\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
|
|
Return a C \ctype{unsigned long} representation of the contents of
|
|
\var{pylong}. If \var{pylong} is greater than
|
|
\constant{ULONG_MAX}\ttindex{ULONG_MAX}, an
|
|
\exception{OverflowError} is raised.
|
|
\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PY_LONG_LONG}{PyLong_AsLongLong}{PyObject *pylong}
|
|
Return a C \ctype{long long} from a Python long integer. If
|
|
\var{pylong} cannot be represented as a \ctype{long long}, an
|
|
\exception{OverflowError} will be raised.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyLong_AsUnsignedLongLong}{PyObject
|
|
*pylong}
|
|
Return a C \ctype{unsigned long long} from a Python long integer.
|
|
If \var{pylong} cannot be represented as an \ctype{unsigned long
|
|
long}, an \exception{OverflowError} will be raised if the value is
|
|
positive, or a \exception{TypeError} will be raised if the value is
|
|
negative.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLongMask}{PyObject *io}
|
|
Return a C \ctype{unsigned long} from a Python long integer, without
|
|
checking for overflow.
|
|
\versionadded{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyLong_AsUnsignedLongLongMask}{PyObject *io}
|
|
Return a C \ctype{unsigned long long} from a Python long integer, without
|
|
checking for overflow.
|
|
\versionadded{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
|
|
Return a C \ctype{double} representation of the contents of
|
|
\var{pylong}. If \var{pylong} cannot be approximately represented
|
|
as a \ctype{double}, an \exception{OverflowError} exception is
|
|
raised and \code{-1.0} will be returned.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong}
|
|
Convert a Python integer or long integer \var{pylong} to a C
|
|
\ctype{void} pointer. If \var{pylong} cannot be converted, an
|
|
\exception{OverflowError} will be raised. This is only assured to
|
|
produce a usable \ctype{void} pointer for values created with
|
|
\cfunction{PyLong_FromVoidPtr()}.
|
|
\versionadded{1.5.2}
|
|
\versionchanged[For values outside 0..LONG_MAX, both signed and
|
|
unsigned integers are acccepted]{2.5}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Floating Point Objects \label{floatObjects}}
|
|
|
|
\obindex{floating point}
|
|
\begin{ctypedesc}{PyFloatObject}
|
|
This subtype of \ctype{PyObject} represents a Python floating point
|
|
object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python floating
|
|
point type. This is the same object as \code{float} and
|
|
\code{types.FloatType}.
|
|
\withsubitem{(in modules types)}{\ttindex{FloatType}}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
|
|
Return true if its argument is a \ctype{PyFloatObject} or a subtype
|
|
of \ctype{PyFloatObject}.
|
|
\versionchanged[Allowed subtypes to be accepted]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p}
|
|
Return true if its argument is a \ctype{PyFloatObject}, but not a
|
|
subtype of \ctype{PyFloatObject}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFloat_FromString}{PyObject *str, char **pend}
|
|
Create a \ctype{PyFloatObject} object based on the string value in
|
|
\var{str}, or \NULL{} on failure. The \var{pend} argument is ignored. It
|
|
remains only for backward compatibility.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
|
|
Create a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
|
|
failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
|
|
Return a C \ctype{double} representation of the contents of
|
|
\var{pyfloat}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
|
|
Return a C \ctype{double} representation of the contents of
|
|
\var{pyfloat}, but without error checking.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Complex Number Objects \label{complexObjects}}
|
|
|
|
\obindex{complex number}
|
|
Python's complex number objects are implemented as two distinct types
|
|
when viewed from the C API: one is the Python object exposed to
|
|
Python programs, and the other is a C structure which represents the
|
|
actual complex number value. The API provides functions for working
|
|
with both.
|
|
|
|
\subsubsection{Complex Numbers as C Structures}
|
|
|
|
Note that the functions which accept these structures as parameters
|
|
and return them as results do so \emph{by value} rather than
|
|
dereferencing them through pointers. This is consistent throughout
|
|
the API.
|
|
|
|
\begin{ctypedesc}{Py_complex}
|
|
The C structure which corresponds to the value portion of a Python
|
|
complex number object. Most of the functions for dealing with
|
|
complex number objects use structures of this type as input or
|
|
output values, as appropriate. It is defined as:
|
|
|
|
\begin{verbatim}
|
|
typedef struct {
|
|
double real;
|
|
double imag;
|
|
} Py_complex;
|
|
\end{verbatim}
|
|
\end{ctypedesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
|
|
Return the sum of two complex numbers, using the C
|
|
\ctype{Py_complex} representation.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
|
|
Return the difference between two complex numbers, using the C
|
|
\ctype{Py_complex} representation.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
|
|
Return the negation of the complex number \var{complex}, using the C
|
|
\ctype{Py_complex} representation.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
|
|
Return the product of two complex numbers, using the C
|
|
\ctype{Py_complex} representation.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
|
|
Py_complex divisor}
|
|
Return the quotient of two complex numbers, using the C
|
|
\ctype{Py_complex} representation.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
|
|
Return the exponentiation of \var{num} by \var{exp}, using the C
|
|
\ctype{Py_complex} representation.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsubsection{Complex Numbers as Python Objects}
|
|
|
|
\begin{ctypedesc}{PyComplexObject}
|
|
This subtype of \ctype{PyObject} represents a Python complex number
|
|
object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python complex
|
|
number type. It is the same object as \code{complex} and
|
|
\code{types.ComplexType}.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
|
|
Return true if its argument is a \ctype{PyComplexObject} or a
|
|
subtype of \ctype{PyComplexObject}.
|
|
\versionchanged[Allowed subtypes to be accepted]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p}
|
|
Return true if its argument is a \ctype{PyComplexObject}, but not a
|
|
subtype of \ctype{PyComplexObject}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
|
|
Create a new Python complex number object from a C
|
|
\ctype{Py_complex} value.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
|
|
Return a new \ctype{PyComplexObject} object from \var{real} and
|
|
\var{imag}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
|
|
Return the real part of \var{op} as a C \ctype{double}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
|
|
Return the imaginary part of \var{op} as a C \ctype{double}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
|
|
Return the \ctype{Py_complex} value of the complex number
|
|
\var{op}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
|
|
\section{Sequence Objects \label{sequenceObjects}}
|
|
|
|
\obindex{sequence}
|
|
Generic operations on sequence objects were discussed in the previous
|
|
chapter; this section deals with the specific kinds of sequence
|
|
objects that are intrinsic to the Python language.
|
|
|
|
|
|
\subsection{String Objects \label{stringObjects}}
|
|
|
|
These functions raise \exception{TypeError} when expecting a string
|
|
parameter and are called with a non-string parameter.
|
|
|
|
\obindex{string}
|
|
\begin{ctypedesc}{PyStringObject}
|
|
This subtype of \ctype{PyObject} represents a Python string object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyString_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python string
|
|
type; it is the same object as \code{str} and \code{types.StringType}
|
|
in the Python layer.
|
|
\withsubitem{(in module types)}{\ttindex{StringType}}.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
|
|
Return true if the object \var{o} is a string object or an instance
|
|
of a subtype of the string type.
|
|
\versionchanged[Allowed subtypes to be accepted]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o}
|
|
Return true if the object \var{o} is a string object, but not an
|
|
instance of a subtype of the string type.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
|
|
Return a new string object with the value \var{v} on success, and
|
|
\NULL{} on failure. The parameter \var{v} must not be \NULL{}; it
|
|
will not be checked.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
|
|
Py_ssize_t len}
|
|
Return a new string object with the value \var{v} and length
|
|
\var{len} on success, and \NULL{} on failure. If \var{v} is
|
|
\NULL{}, the contents of the string are uninitialized.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...}
|
|
Take a C \cfunction{printf()}-style \var{format} string and a
|
|
variable number of arguments, calculate the size of the resulting
|
|
Python string and return a string with the values formatted into
|
|
it. The variable arguments must be C types and must correspond
|
|
exactly to the format characters in the \var{format} string. The
|
|
following format characters are allowed:
|
|
|
|
% This should be exactly the same as the table in PyErr_Format.
|
|
% One should just refer to the other.
|
|
|
|
% The descriptions for %zd and %zu are wrong, but the truth is complicated
|
|
% because not all compilers support the %z width modifier -- we fake it
|
|
% when necessary via interpolating PY_FORMAT_SIZE_T.
|
|
|
|
% %u, %lu, %zu should have "new in Python 2.5" blurbs.
|
|
|
|
\begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
|
|
\lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
|
|
\lineiii{\%c}{int}{A single character, represented as an C int.}
|
|
\lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
|
|
\lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
|
|
\lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
|
|
\lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
|
|
\lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
|
|
\lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.}
|
|
\lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
|
|
\lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
|
|
\lineiii{\%s}{char*}{A null-terminated C character array.}
|
|
\lineiii{\%p}{void*}{The hex representation of a C pointer.
|
|
Mostly equivalent to \code{printf("\%p")} except that it is
|
|
guaranteed to start with the literal \code{0x} regardless of
|
|
what the platform's \code{printf} yields.}
|
|
\end{tableiii}
|
|
|
|
An unrecognized format character causes all the rest of the format
|
|
string to be copied as-is to the result string, and any extra
|
|
arguments discarded.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format,
|
|
va_list vargs}
|
|
Identical to \function{PyString_FromFormat()} except that it takes
|
|
exactly two arguments.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyString_Size}{PyObject *string}
|
|
Return the length of the string in string object \var{string}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyString_GET_SIZE}{PyObject *string}
|
|
Macro form of \cfunction{PyString_Size()} but without error
|
|
checking.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
|
|
Return a NUL-terminated representation of the contents of
|
|
\var{string}. The pointer refers to the internal buffer of
|
|
\var{string}, not a copy. The data must not be modified in any way,
|
|
unless the string was just created using
|
|
\code{PyString_FromStringAndSize(NULL, \var{size})}.
|
|
It must not be deallocated. If \var{string} is a Unicode object,
|
|
this function computes the default encoding of \var{string} and
|
|
operates on that. If \var{string} is not a string object at all,
|
|
\cfunction{PyString_AsString()} returns \NULL{} and raises
|
|
\exception{TypeError}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
|
|
Macro form of \cfunction{PyString_AsString()} but without error
|
|
checking. Only string objects are supported; no Unicode objects
|
|
should be passed.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
|
|
char **buffer,
|
|
Py_ssize_t *length}
|
|
Return a NUL-terminated representation of the contents of the
|
|
object \var{obj} through the output variables \var{buffer} and
|
|
\var{length}.
|
|
|
|
The function accepts both string and Unicode objects as input. For
|
|
Unicode objects it returns the default encoded version of the
|
|
object. If \var{length} is \NULL{}, the resulting buffer may not
|
|
contain NUL characters; if it does, the function returns \code{-1}
|
|
and a \exception{TypeError} is raised.
|
|
|
|
The buffer refers to an internal string buffer of \var{obj}, not a
|
|
copy. The data must not be modified in any way, unless the string
|
|
was just created using \code{PyString_FromStringAndSize(NULL,
|
|
\var{size})}. It must not be deallocated. If \var{string} is a
|
|
Unicode object, this function computes the default encoding of
|
|
\var{string} and operates on that. If \var{string} is not a string
|
|
object at all, \cfunction{PyString_AsStringAndSize()} returns
|
|
\code{-1} and raises \exception{TypeError}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
|
|
PyObject *newpart}
|
|
Create a new string object in \var{*string} containing the contents
|
|
of \var{newpart} appended to \var{string}; the caller will own the
|
|
new reference. The reference to the old value of \var{string} will
|
|
be stolen. If the new string cannot be created, the old reference
|
|
to \var{string} will still be discarded and the value of
|
|
\var{*string} will be set to \NULL{}; the appropriate exception will
|
|
be set.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
|
|
PyObject *newpart}
|
|
Create a new string object in \var{*string} containing the contents
|
|
of \var{newpart} appended to \var{string}. This version decrements
|
|
the reference count of \var{newpart}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, Py_ssize_t newsize}
|
|
A way to resize a string object even though it is ``immutable''.
|
|
Only use this to build up a brand new string object; don't use this
|
|
if the string may already be known in other parts of the code. It
|
|
is an error to call this function if the refcount on the input string
|
|
object is not one.
|
|
Pass the address of an existing string object as an lvalue (it may
|
|
be written into), and the new size desired. On success, \var{*string}
|
|
holds the resized string object and \code{0} is returned; the address in
|
|
\var{*string} may differ from its input value. If the
|
|
reallocation fails, the original string object at \var{*string} is
|
|
deallocated, \var{*string} is set to \NULL{}, a memory exception is set,
|
|
and \code{-1} is returned.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
|
|
PyObject *args}
|
|
Return 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.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
|
|
Intern the argument \var{*string} in place. The argument must be
|
|
the address of a pointer variable pointing to a Python string
|
|
object. If there is an existing interned string that is the same as
|
|
\var{*string}, it sets \var{*string} to it (decrementing the
|
|
reference count of the old string object and incrementing the
|
|
reference count of the interned string object), otherwise it leaves
|
|
\var{*string} alone and interns it (incrementing its reference
|
|
count). (Clarification: even though there is a lot of talk about
|
|
reference counts, think of this function as reference-count-neutral;
|
|
you own the object after the call if and only if you owned it before
|
|
the call.)
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
|
|
A combination of \cfunction{PyString_FromString()} and
|
|
\cfunction{PyString_InternInPlace()}, returning either a new string
|
|
object that has been interned, or a new (``owned'') reference to an
|
|
earlier interned string object with the same value.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s,
|
|
Py_ssize_t size,
|
|
const char *encoding,
|
|
const char *errors}
|
|
Create an object by decoding \var{size} bytes of the encoded
|
|
buffer \var{s} using the codec registered for
|
|
\var{encoding}. \var{encoding} and \var{errors} have the same
|
|
meaning as the parameters of the same name in the
|
|
\function{unicode()} built-in function. The codec to be used is
|
|
looked up using the Python codec registry. Return \NULL{} if
|
|
an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str,
|
|
const char *encoding,
|
|
const char *errors}
|
|
Decode a string object by passing it to the codec registered for
|
|
\var{encoding} and return the result as Python
|
|
object. \var{encoding} and \var{errors} have the same meaning as the
|
|
parameters of the same name in the string \method{encode()} method.
|
|
The codec to be used is looked up using the Python codec registry.
|
|
Return \NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s,
|
|
Py_ssize_t size,
|
|
const char *encoding,
|
|
const char *errors}
|
|
Encode the \ctype{char} buffer of the given size by passing it to
|
|
the codec registered for \var{encoding} and return a Python object.
|
|
\var{encoding} and \var{errors} have the same meaning as the
|
|
parameters of the same name in the string \method{encode()} method.
|
|
The codec to be used is looked up using the Python codec
|
|
registry. Return \NULL{} if an exception was raised by the
|
|
codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str,
|
|
const char *encoding,
|
|
const char *errors}
|
|
Encode a string object using the codec registered for
|
|
\var{encoding} and return the result as Python object.
|
|
\var{encoding} and \var{errors} have the same meaning as the
|
|
parameters of the same name in the string \method{encode()} method.
|
|
The codec to be used is looked up using the Python codec registry.
|
|
Return \NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Unicode Objects \label{unicodeObjects}}
|
|
\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
|
|
|
|
%--- Unicode Type -------------------------------------------------------
|
|
|
|
These are the basic Unicode object types used for the Unicode
|
|
implementation in Python:
|
|
|
|
\begin{ctypedesc}{Py_UNICODE}
|
|
This type represents the storage type which is used by Python
|
|
internally as basis for holding Unicode ordinals. Python's default
|
|
builds use a 16-bit type for \ctype{Py_UNICODE} and store Unicode
|
|
values internally as UCS2. It is also possible to build a UCS4
|
|
version of Python (most recent Linux distributions come with UCS4
|
|
builds of Python). These builds then use a 32-bit type for
|
|
\ctype{Py_UNICODE} and store Unicode data internally as UCS4. On
|
|
platforms where \ctype{wchar_t} is available and compatible with the
|
|
chosen Python Unicode build variant, \ctype{Py_UNICODE} is a typedef
|
|
alias for \ctype{wchar_t} to enhance native platform compatibility.
|
|
On all other platforms, \ctype{Py_UNICODE} is a typedef alias for
|
|
either \ctype{unsigned short} (UCS2) or \ctype{unsigned long}
|
|
(UCS4).
|
|
\end{ctypedesc}
|
|
|
|
Note that UCS2 and UCS4 Python builds are not binary compatible.
|
|
Please keep this in mind when writing extensions or interfaces.
|
|
|
|
\begin{ctypedesc}{PyUnicodeObject}
|
|
This subtype of \ctype{PyObject} represents a Python Unicode object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python Unicode
|
|
type. It is exposed to Python code as \code{unicode} and
|
|
\code{types.UnicodeType}.
|
|
\end{cvardesc}
|
|
|
|
The following APIs are really C macros and can be used to do fast
|
|
checks and to access internal read-only data of Unicode objects:
|
|
|
|
\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
|
|
Return true if the object \var{o} is a Unicode object or an
|
|
instance of a Unicode subtype.
|
|
\versionchanged[Allowed subtypes to be accepted]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o}
|
|
Return true if the object \var{o} is a Unicode object, but not an
|
|
instance of a subtype.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_SIZE}{PyObject *o}
|
|
Return the size of the object. \var{o} has to be a
|
|
\ctype{PyUnicodeObject} (not checked).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
|
|
Return the size of the object's internal buffer in bytes. \var{o}
|
|
has to be a \ctype{PyUnicodeObject} (not checked).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o}
|
|
Return a pointer to the internal \ctype{Py_UNICODE} buffer of the
|
|
object. \var{o} has to be a \ctype{PyUnicodeObject} (not checked).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o}
|
|
Return a pointer to the internal buffer of the object.
|
|
\var{o} has to be a \ctype{PyUnicodeObject} (not checked).
|
|
\end{cfuncdesc}
|
|
|
|
% --- Unicode character properties ---------------------------------------
|
|
|
|
Unicode provides many different character properties. The most often
|
|
needed ones are available through these macros which are mapped to C
|
|
functions depending on the Python configuration.
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch}
|
|
Return 1 or 0 depending on whether \var{ch} is a whitespace
|
|
character.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch}
|
|
Return 1 or 0 depending on whether \var{ch} is a lowercase character.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
|
|
Return 1 or 0 depending on whether \var{ch} is an uppercase
|
|
character.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch}
|
|
Return 1 or 0 depending on whether \var{ch} is a titlecase character.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch}
|
|
Return 1 or 0 depending on whether \var{ch} is a linebreak character.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch}
|
|
Return 1 or 0 depending on whether \var{ch} is a decimal character.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
|
|
Return 1 or 0 depending on whether \var{ch} is a digit character.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch}
|
|
Return 1 or 0 depending on whether \var{ch} is a numeric character.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
|
|
Return 1 or 0 depending on whether \var{ch} is an alphabetic
|
|
character.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
|
|
Return 1 or 0 depending on whether \var{ch} is an alphanumeric
|
|
character.
|
|
\end{cfuncdesc}
|
|
|
|
These APIs can be used for fast direct character conversions:
|
|
|
|
\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch}
|
|
Return the character \var{ch} converted to lower case.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch}
|
|
Return the character \var{ch} converted to upper case.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch}
|
|
Return the character \var{ch} converted to title case.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch}
|
|
Return the character \var{ch} converted to a decimal positive
|
|
integer. Return \code{-1} if this is not possible. This macro
|
|
does not raise exceptions.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
|
|
Return the character \var{ch} converted to a single digit integer.
|
|
Return \code{-1} if this is not possible. This macro does not raise
|
|
exceptions.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch}
|
|
Return the character \var{ch} converted to a double.
|
|
Return \code{-1.0} if this is not possible. This macro does not raise
|
|
exceptions.
|
|
\end{cfuncdesc}
|
|
|
|
% --- Plain Py_UNICODE ---------------------------------------------------
|
|
|
|
To create Unicode objects and access their basic sequence properties,
|
|
use these APIs:
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u,
|
|
Py_ssize_t size}
|
|
Create a Unicode Object from the Py_UNICODE buffer \var{u} of the
|
|
given size. \var{u} may be \NULL{} which causes the contents to be
|
|
undefined. It is the user's responsibility to fill in the needed
|
|
data. The buffer is copied into the new object. If the buffer is
|
|
not \NULL{}, the return value might be a shared object. Therefore,
|
|
modification of the resulting Unicode object is only allowed when
|
|
\var{u} is \NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode}
|
|
Return a read-only pointer to the Unicode object's internal
|
|
\ctype{Py_UNICODE} buffer, \NULL{} if \var{unicode} is not a Unicode
|
|
object.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GetSize}{PyObject *unicode}
|
|
Return the length of the Unicode object.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj,
|
|
const char *encoding,
|
|
const char *errors}
|
|
Coerce an encoded object \var{obj} to an Unicode object and return a
|
|
reference with incremented refcount.
|
|
|
|
String and other char buffer compatible objects are decoded
|
|
according to the given encoding and using the error handling
|
|
defined by errors. Both can be \NULL{} to have the interface
|
|
use the default values (see the next section for details).
|
|
|
|
All other objects, including Unicode objects, cause a
|
|
\exception{TypeError} to be set.
|
|
|
|
The API returns \NULL{} if there was an error. The caller is
|
|
responsible for decref'ing the returned objects.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj}
|
|
Shortcut for \code{PyUnicode_FromEncodedObject(obj, NULL, "strict")}
|
|
which is used throughout the interpreter whenever coercion to
|
|
Unicode is needed.
|
|
\end{cfuncdesc}
|
|
|
|
% --- wchar_t support for platforms which support it ---------------------
|
|
|
|
If the platform supports \ctype{wchar_t} and provides a header file
|
|
wchar.h, Python can interface directly to this type using the
|
|
following functions. Support is optimized if Python's own
|
|
\ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}.
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w,
|
|
Py_ssize_t size}
|
|
Create a Unicode object from the \ctype{wchar_t} buffer \var{w} of
|
|
the given size. Return \NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
|
|
wchar_t *w,
|
|
Py_ssize_t size}
|
|
Copy the Unicode object contents into the \ctype{wchar_t} buffer
|
|
\var{w}. At most \var{size} \ctype{wchar_t} characters are copied
|
|
(excluding a possibly trailing 0-termination character). Return
|
|
the number of \ctype{wchar_t} characters copied or -1 in case of an
|
|
error. Note that the resulting \ctype{wchar_t} string may or may
|
|
not be 0-terminated. It is the responsibility of the caller to make
|
|
sure that the \ctype{wchar_t} string is 0-terminated in case this is
|
|
required by the application.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsubsection{Built-in Codecs \label{builtinCodecs}}
|
|
|
|
Python provides a set of builtin codecs which are written in C
|
|
for speed. All of these codecs are directly usable via the
|
|
following functions.
|
|
|
|
Many of the following APIs take two arguments encoding and
|
|
errors. These parameters encoding and errors have the same semantics
|
|
as the ones of the builtin unicode() Unicode object constructor.
|
|
|
|
Setting encoding to \NULL{} causes the default encoding to be used
|
|
which is \ASCII. The file system calls should use
|
|
\cdata{Py_FileSystemDefaultEncoding} as the encoding for file
|
|
names. This variable should be treated as read-only: On some systems,
|
|
it will be a pointer to a static string, on others, it will change at
|
|
run-time (such as when the application invokes setlocale).
|
|
|
|
Error handling is set by errors which may also be set to \NULL{}
|
|
meaning to use the default handling defined for the codec. Default
|
|
error handling for all builtin codecs is ``strict''
|
|
(\exception{ValueError} is raised).
|
|
|
|
The codecs all use a similar interface. Only deviation from the
|
|
following generic ones are documented for simplicity.
|
|
|
|
% --- Generic Codecs -----------------------------------------------------
|
|
|
|
These are the generic codec APIs:
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
|
|
Py_ssize_t 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
|
|
\function{unicode()} builtin function. The codec to be used is
|
|
looked up using the Python codec registry. Return \NULL{} if an
|
|
exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s,
|
|
Py_ssize_t size,
|
|
const char *encoding,
|
|
const char *errors}
|
|
Encode the \ctype{Py_UNICODE} buffer of the given size and return
|
|
a Python string object. \var{encoding} and \var{errors} have the
|
|
same meaning as the parameters of the same name in the Unicode
|
|
\method{encode()} method. The codec to be used is looked up using
|
|
the Python codec registry. Return \NULL{} if an exception was
|
|
raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
|
|
const char *encoding,
|
|
const char *errors}
|
|
Encode a Unicode object and return 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 \method{encode()} method.
|
|
The codec to be used is looked up using the Python codec registry.
|
|
Return \NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
% --- UTF-8 Codecs -------------------------------------------------------
|
|
|
|
These are the UTF-8 codec APIs:
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
|
|
Py_ssize_t size,
|
|
const char *errors}
|
|
Create a Unicode object by decoding \var{size} bytes of the UTF-8
|
|
encoded string \var{s}. Return \NULL{} if an exception was raised
|
|
by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8Stateful}{const char *s,
|
|
Py_ssize_t size,
|
|
const char *errors,
|
|
Py_ssize_t *consumed}
|
|
If \var{consumed} is \NULL{}, behave like \cfunction{PyUnicode_DecodeUTF8()}.
|
|
If \var{consumed} is not \NULL{}, trailing incomplete UTF-8 byte sequences
|
|
will not be treated as an error. Those bytes will not be decoded and the
|
|
number of bytes that have been decoded will be stored in \var{consumed}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s,
|
|
Py_ssize_t size,
|
|
const char *errors}
|
|
Encode the \ctype{Py_UNICODE} buffer of the given size using UTF-8
|
|
and return a Python string object. Return \NULL{} if an exception
|
|
was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
|
|
Encode a Unicode objects using UTF-8 and return the result as
|
|
Python string object. Error handling is ``strict''. Return
|
|
\NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
% --- UTF-16 Codecs ------------------------------------------------------ */
|
|
|
|
These are the UTF-16 codec APIs:
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
|
|
Py_ssize_t size,
|
|
const char *errors,
|
|
int *byteorder}
|
|
Decode \var{length} bytes from a UTF-16 encoded buffer string and
|
|
return the corresponding Unicode object. \var{errors} (if
|
|
non-\NULL{}) defines the error handling. It defaults to ``strict''.
|
|
|
|
If \var{byteorder} is non-\NULL{}, the decoder starts decoding using
|
|
the given byte order:
|
|
|
|
\begin{verbatim}
|
|
*byteorder == -1: little endian
|
|
*byteorder == 0: native order
|
|
*byteorder == 1: big endian
|
|
\end{verbatim}
|
|
|
|
and then switches according to all byte order marks (BOM) it finds
|
|
in the input data. BOMs are not copied into the resulting Unicode
|
|
string. After completion, \var{*byteorder} is set to the current
|
|
byte order at the end of input data.
|
|
|
|
If \var{byteorder} is \NULL{}, the codec starts in native order mode.
|
|
|
|
Return \NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16Stateful}{const char *s,
|
|
Py_ssize_t size,
|
|
const char *errors,
|
|
int *byteorder,
|
|
Py_ssize_t *consumed}
|
|
If \var{consumed} is \NULL{}, behave like
|
|
\cfunction{PyUnicode_DecodeUTF16()}. If \var{consumed} is not \NULL{},
|
|
\cfunction{PyUnicode_DecodeUTF16Stateful()} will not treat trailing incomplete
|
|
UTF-16 byte sequences (such as an odd number of bytes or a split surrogate pair)
|
|
as an error. Those bytes will not be decoded and the number of bytes that
|
|
have been decoded will be stored in \var{consumed}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s,
|
|
Py_ssize_t size,
|
|
const char *errors,
|
|
int byteorder}
|
|
Return a Python string object holding the UTF-16 encoded value of
|
|
the Unicode data in \var{s}. If \var{byteorder} is not \code{0},
|
|
output is written according to the following byte order:
|
|
|
|
\begin{verbatim}
|
|
byteorder == -1: little endian
|
|
byteorder == 0: native byte order (writes a BOM mark)
|
|
byteorder == 1: big endian
|
|
\end{verbatim}
|
|
|
|
If byteorder is \code{0}, the output string will always start with
|
|
the Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark
|
|
is prepended.
|
|
|
|
If \var{Py_UNICODE_WIDE} is defined, a single \ctype{Py_UNICODE}
|
|
value may get represented as a surrogate pair. If it is not
|
|
defined, each \ctype{Py_UNICODE} values is interpreted as an
|
|
UCS-2 character.
|
|
|
|
Return \NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
|
|
Return a Python string using the UTF-16 encoding in native byte
|
|
order. The string always starts with a BOM mark. Error handling is
|
|
``strict''. Return \NULL{} if an exception was raised by the
|
|
codec.
|
|
\end{cfuncdesc}
|
|
|
|
% --- Unicode-Escape Codecs ----------------------------------------------
|
|
|
|
These are the ``Unicode Escape'' codec APIs:
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
|
|
Py_ssize_t size,
|
|
const char *errors}
|
|
Create a Unicode object by decoding \var{size} bytes of the
|
|
Unicode-Escape encoded string \var{s}. Return \NULL{} if an
|
|
exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s,
|
|
Py_ssize_t size}
|
|
Encode the \ctype{Py_UNICODE} buffer of the given size using
|
|
Unicode-Escape and return a Python string object. Return \NULL{}
|
|
if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
|
|
Encode a Unicode objects using Unicode-Escape and return the
|
|
result as Python string object. Error handling is ``strict''.
|
|
Return \NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
% --- Raw-Unicode-Escape Codecs ------------------------------------------
|
|
|
|
These are the ``Raw Unicode Escape'' codec APIs:
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
|
|
Py_ssize_t size,
|
|
const char *errors}
|
|
Create a Unicode object by decoding \var{size} bytes of the
|
|
Raw-Unicode-Escape encoded string \var{s}. Return \NULL{} if an
|
|
exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s,
|
|
Py_ssize_t size,
|
|
const char *errors}
|
|
Encode the \ctype{Py_UNICODE} buffer of the given size using
|
|
Raw-Unicode-Escape and return a Python string object. Return
|
|
\NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
|
|
Encode a Unicode objects using Raw-Unicode-Escape and return the
|
|
result as Python string object. Error handling is ``strict''.
|
|
Return \NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
% --- Latin-1 Codecs -----------------------------------------------------
|
|
|
|
These are the Latin-1 codec APIs:
|
|
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,
|
|
Py_ssize_t size,
|
|
const char *errors}
|
|
Create a Unicode object by decoding \var{size} bytes of the Latin-1
|
|
encoded string \var{s}. Return \NULL{} if an exception was raised
|
|
by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
|
|
Py_ssize_t size,
|
|
const char *errors}
|
|
Encode the \ctype{Py_UNICODE} buffer of the given size using
|
|
Latin-1 and return a Python string object. Return \NULL{} if an
|
|
exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
|
|
Encode a Unicode objects using Latin-1 and return the result as
|
|
Python string object. Error handling is ``strict''. Return
|
|
\NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
% --- ASCII Codecs -------------------------------------------------------
|
|
|
|
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,
|
|
Py_ssize_t size,
|
|
const char *errors}
|
|
Create a Unicode object by decoding \var{size} bytes of the
|
|
\ASCII{} encoded string \var{s}. Return \NULL{} if an exception
|
|
was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
|
|
Py_ssize_t size,
|
|
const char *errors}
|
|
Encode the \ctype{Py_UNICODE} buffer of the given size using
|
|
\ASCII{} and return a Python string object. Return \NULL{} if an
|
|
exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
|
|
Encode a Unicode objects using \ASCII{} and return the result as
|
|
Python string object. Error handling is ``strict''. Return
|
|
\NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
% --- Character Map Codecs -----------------------------------------------
|
|
|
|
These are the mapping codec APIs:
|
|
|
|
This codec is special in that it can be used to implement many
|
|
different codecs (and this is in fact what was done to obtain most of
|
|
the standard codecs included in the \module{encodings} package). The
|
|
codec uses mapping to encode and decode characters.
|
|
|
|
Decoding mappings must map single string characters to single Unicode
|
|
characters, integers (which are then interpreted as Unicode ordinals)
|
|
or None (meaning "undefined mapping" and causing an error).
|
|
|
|
Encoding mappings must map single Unicode characters to single string
|
|
characters, integers (which are then interpreted as Latin-1 ordinals)
|
|
or None (meaning "undefined mapping" and causing an error).
|
|
|
|
The mapping objects provided must only support the __getitem__ mapping
|
|
interface.
|
|
|
|
If a character lookup fails with a LookupError, the character is
|
|
copied as-is meaning that its ordinal value will be interpreted as
|
|
Unicode or Latin-1 ordinal resp. Because of this, mappings only need
|
|
to contain those mappings which map characters to different code
|
|
points.
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
|
|
Py_ssize_t size,
|
|
PyObject *mapping,
|
|
const char *errors}
|
|
Create a Unicode object by decoding \var{size} bytes of the encoded
|
|
string \var{s} using the given \var{mapping} object. Return
|
|
\NULL{} if an exception was raised by the codec. If \var{mapping} is \NULL{}
|
|
latin-1 decoding will be done. Else it can be a dictionary mapping byte or a
|
|
unicode string, which is treated as a lookup table. Byte values greater
|
|
that the length of the string and U+FFFE "characters" are treated as
|
|
"undefined mapping".
|
|
\versionchanged[Allowed unicode string as mapping argument]{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s,
|
|
Py_ssize_t size,
|
|
PyObject *mapping,
|
|
const char *errors}
|
|
Encode the \ctype{Py_UNICODE} buffer of the given size using the
|
|
given \var{mapping} object and return a Python string object.
|
|
Return \NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
|
|
PyObject *mapping}
|
|
Encode a Unicode objects using the given \var{mapping} object and
|
|
return the result as Python string object. Error handling is
|
|
``strict''. Return \NULL{} if an exception was raised by the
|
|
codec.
|
|
\end{cfuncdesc}
|
|
|
|
The following codec API is special in that maps Unicode to Unicode.
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s,
|
|
Py_ssize_t size,
|
|
PyObject *table,
|
|
const char *errors}
|
|
Translate a \ctype{Py_UNICODE} buffer of the given length by
|
|
applying a character mapping \var{table} to it and return the
|
|
resulting Unicode object. Return \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).
|
|
|
|
Mapping tables need only provide the \method{__getitem__()}
|
|
interface; dictionaries and sequences work well. Unmapped character
|
|
ordinals (ones which cause a \exception{LookupError}) are left
|
|
untouched and are copied as-is.
|
|
\end{cfuncdesc}
|
|
|
|
% --- MBCS codecs for Windows --------------------------------------------
|
|
|
|
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.
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
|
|
Py_ssize_t size,
|
|
const char *errors}
|
|
Create a Unicode object by decoding \var{size} bytes of the MBCS
|
|
encoded string \var{s}. Return \NULL{} if an exception was
|
|
raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCSStateful}{const char *s,
|
|
int size,
|
|
const char *errors,
|
|
int *consumed}
|
|
If \var{consumed} is \NULL{}, behave like
|
|
\cfunction{PyUnicode_DecodeMBCS()}. If \var{consumed} is not \NULL{},
|
|
\cfunction{PyUnicode_DecodeMBCSStateful()} will not decode trailing lead
|
|
byte and the number of bytes that have been decoded will be stored in
|
|
\var{consumed}.
|
|
\versionadded{2.5}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
|
|
Py_ssize_t size,
|
|
const char *errors}
|
|
Encode the \ctype{Py_UNICODE} buffer of the given size using MBCS
|
|
and return a Python string object. Return \NULL{} if an exception
|
|
was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
|
|
Encode a Unicode objects using MBCS and return the result as
|
|
Python string object. Error handling is ``strict''. Return
|
|
\NULL{} if an exception was raised by the codec.
|
|
\end{cfuncdesc}
|
|
|
|
% --- Methods & Slots ----------------------------------------------------
|
|
|
|
\subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
|
|
|
|
The following APIs are capable of handling Unicode objects and strings
|
|
on input (we refer to them as strings in the descriptions) and return
|
|
Unicode objects or integers as appropriate.
|
|
|
|
They all return \NULL{} or \code{-1} if an exception occurs.
|
|
|
|
\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,
|
|
Py_ssize_t maxsplit}
|
|
Split a string giving a list of Unicode strings. If sep is \NULL{},
|
|
splitting will be done at all whitespace substrings. Otherwise,
|
|
splits occur at the given separator. At most \var{maxsplit} splits
|
|
will be done. If negative, no limit is set. Separators are not
|
|
included in the resulting list.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s,
|
|
int keepend}
|
|
Split a Unicode string at line breaks, returning a list of Unicode
|
|
strings. CRLF is considered to be one line break. If \var{keepend}
|
|
is 0, 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.
|
|
|
|
The mapping table must map Unicode ordinal integers to Unicode
|
|
ordinal integers or None (causing deletion of the character).
|
|
|
|
Mapping tables need only provide the \method{__getitem__()}
|
|
interface; dictionaries and sequences work well. Unmapped character
|
|
ordinals (ones which cause a \exception{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}
|
|
|
|
\begin{cfuncdesc}{int}{PyUnicode_Tailmatch}{PyObject *str,
|
|
PyObject *substr,
|
|
Py_ssize_t start,
|
|
Py_ssize_t 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.
|
|
Return \code{-1} if an error occurred.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Find}{PyObject *str,
|
|
PyObject *substr,
|
|
Py_ssize_t start,
|
|
Py_ssize_t 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,
|
|
\var{direction} == -1 a backward search). The return value is the
|
|
index of the first match; a value of \code{-1} indicates that no
|
|
match was found, and \code{-2} indicates that an error occurred and
|
|
an exception has been set.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Count}{PyObject *str,
|
|
PyObject *substr,
|
|
Py_ssize_t start,
|
|
Py_ssize_t end}
|
|
Return the number of non-overlapping occurrences of \var{substr} in
|
|
\code{\var{str}[\var{start}:\var{end}]}. Return \code{-1} if an
|
|
error occurred.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
|
|
PyObject *substr,
|
|
PyObject *replstr,
|
|
Py_ssize_t 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}
|
|
Compare two strings and return -1, 0, 1 for less than, equal, and
|
|
greater than, respectively.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyUnicode_RichCompare}{PyObject *left,
|
|
PyObject *right,
|
|
int op}
|
|
|
|
Rich compare two unicode strings and return one of the following:
|
|
\begin{itemize}
|
|
\item \code{NULL} in case an exception was raised
|
|
\item \constant{Py_True} or \constant{Py_False} for successful comparisons
|
|
\item \constant{Py_NotImplemented} in case the type combination is unknown
|
|
\end{itemize}
|
|
|
|
Note that \constant{Py_EQ} and \constant{Py_NE} comparisons can cause a
|
|
\exception{UnicodeWarning} in case the conversion of the arguments to
|
|
Unicode fails with a \exception{UnicodeDecodeError}.
|
|
|
|
Possible values for \var{op} are
|
|
\constant{Py_GT}, \constant{Py_GE}, \constant{Py_EQ},
|
|
\constant{Py_NE}, \constant{Py_LT}, and \constant{Py_LE}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
|
|
PyObject *args}
|
|
Return 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}
|
|
Check whether \var{element} is contained in \var{container} and
|
|
return true or false accordingly.
|
|
|
|
\var{element} has to coerce to a one element Unicode
|
|
string. \code{-1} is returned if there was an error.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Buffer Objects \label{bufferObjects}}
|
|
\sectionauthor{Greg Stein}{gstein@lyra.org}
|
|
|
|
\obindex{buffer}
|
|
Python objects implemented in C can export a group of functions called
|
|
the ``buffer\index{buffer interface} interface.'' These functions can
|
|
be used by an object to expose its data in a raw, byte-oriented
|
|
format. Clients of the object can use the buffer interface to access
|
|
the object data directly, without needing to copy it first.
|
|
|
|
Two examples of objects that support
|
|
the buffer interface are strings and arrays. The string object exposes
|
|
the character contents in the buffer interface's byte-oriented
|
|
form. An array can also expose its contents, but it should be noted
|
|
that array elements may be multi-byte values.
|
|
|
|
An example user of the buffer interface is the file object's
|
|
\method{write()} method. Any object that can export a series of bytes
|
|
through the buffer interface can be written to a file. There are a
|
|
number of format codes to \cfunction{PyArg_ParseTuple()} that operate
|
|
against an object's buffer interface, returning data from the target
|
|
object.
|
|
|
|
More information on the buffer interface is provided in the section
|
|
``Buffer Object Structures'' (section~\ref{buffer-structs}), under
|
|
the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}.
|
|
|
|
A ``buffer object'' is defined in the \file{bufferobject.h} header
|
|
(included by \file{Python.h}). These objects look very similar to
|
|
string objects at the Python programming level: they support slicing,
|
|
indexing, concatenation, and some other standard string
|
|
operations. However, their data can come from one of two sources: from
|
|
a block of memory, or from another object which exports the buffer
|
|
interface.
|
|
|
|
Buffer objects are useful as a way to expose the data from another
|
|
object's buffer interface to the Python programmer. They can also be
|
|
used as a zero-copy slicing mechanism. Using their ability to
|
|
reference a block of memory, it is possible to expose any data to the
|
|
Python programmer quite easily. The memory could be a large, constant
|
|
array in a C extension, it could be a raw block of memory for
|
|
manipulation before passing to an operating system library, or it
|
|
could be used to pass around structured data in its native, in-memory
|
|
format.
|
|
|
|
\begin{ctypedesc}{PyBufferObject}
|
|
This subtype of \ctype{PyObject} represents a buffer object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
|
|
The instance of \ctype{PyTypeObject} which represents the Python
|
|
buffer type; it is the same object as \code{buffer} and
|
|
\code{types.BufferType} in the Python layer.
|
|
\withsubitem{(in module types)}{\ttindex{BufferType}}.
|
|
\end{cvardesc}
|
|
|
|
\begin{cvardesc}{int}{Py_END_OF_BUFFER}
|
|
This constant may be passed as the \var{size} parameter to
|
|
\cfunction{PyBuffer_FromObject()} or
|
|
\cfunction{PyBuffer_FromReadWriteObject()}. It indicates that the
|
|
new \ctype{PyBufferObject} should refer to \var{base} object from
|
|
the specified \var{offset} to the end of its exported buffer. Using
|
|
this enables the caller to avoid querying the \var{base} object for
|
|
its length.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p}
|
|
Return true if the argument has type \cdata{PyBuffer_Type}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base,
|
|
Py_ssize_t offset, Py_ssize_t size}
|
|
Return a new read-only buffer object. This raises
|
|
\exception{TypeError} if \var{base} doesn't support the read-only
|
|
buffer protocol or doesn't provide exactly one buffer segment, or it
|
|
raises \exception{ValueError} if \var{offset} is less than zero. The
|
|
buffer will hold a reference to the \var{base} object, and the
|
|
buffer's contents will refer to the \var{base} object's buffer
|
|
interface, starting as position \var{offset} and extending for
|
|
\var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then
|
|
the new buffer's contents extend to the length of the \var{base}
|
|
object's exported buffer data.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base,
|
|
Py_ssize_t offset,
|
|
Py_ssize_t size}
|
|
Return a new writable buffer object. Parameters and exceptions are
|
|
similar to those for \cfunction{PyBuffer_FromObject()}. If the
|
|
\var{base} object does not export the writeable buffer protocol,
|
|
then \exception{TypeError} is raised.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, Py_ssize_t size}
|
|
Return a new read-only buffer object that reads from a specified
|
|
location in memory, with a specified size. The caller is
|
|
responsible for ensuring that the memory buffer, passed in as
|
|
\var{ptr}, is not deallocated while the returned buffer object
|
|
exists. Raises \exception{ValueError} if \var{size} is less than
|
|
zero. Note that \constant{Py_END_OF_BUFFER} may \emph{not} be
|
|
passed for the \var{size} parameter; \exception{ValueError} will be
|
|
raised in that case.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, Py_ssize_t size}
|
|
Similar to \cfunction{PyBuffer_FromMemory()}, but the returned
|
|
buffer is writable.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{Py_ssize_t size}
|
|
Return a new writable buffer object that maintains its own memory
|
|
buffer of \var{size} bytes. \exception{ValueError} is returned if
|
|
\var{size} is not zero or positive. Note that the memory buffer (as
|
|
returned by \cfunction{PyObject_AsWriteBuffer()}) is not specifically
|
|
aligned.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Tuple Objects \label{tupleObjects}}
|
|
|
|
\obindex{tuple}
|
|
\begin{ctypedesc}{PyTupleObject}
|
|
This subtype of \ctype{PyObject} represents a Python tuple object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python tuple
|
|
type; it is the same object as \code{tuple} and \code{types.TupleType}
|
|
in the Python layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
|
|
Return true if \var{p} is a tuple object or an instance of a subtype
|
|
of the tuple type.
|
|
\versionchanged[Allowed subtypes to be accepted]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTuple_CheckExact}{PyObject *p}
|
|
Return true if \var{p} is a tuple object, but not an instance of a
|
|
subtype of the tuple type.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyTuple_New}{Py_ssize_t len}
|
|
Return a new tuple object of size \var{len}, or \NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyTuple_Pack}{Py_ssize_t n, \moreargs}
|
|
Return a new tuple object of size \var{n}, or \NULL{} on failure.
|
|
The tuple values are initialized to the subsequent \var{n} C arguments
|
|
pointing to Python objects. \samp{PyTuple_Pack(2, \var{a}, \var{b})}
|
|
is equivalent to \samp{Py_BuildValue("(OO)", \var{a}, \var{b})}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
|
|
Take a pointer to a tuple object, and return the size of that
|
|
tuple.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTuple_GET_SIZE}{PyObject *p}
|
|
Return the size of the tuple \var{p}, which must be non-\NULL{} and
|
|
point to a tuple; no error checking is performed.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, Py_ssize_t pos}
|
|
Return the object at position \var{pos} in the tuple pointed to by
|
|
\var{p}. If \var{pos} is out of bounds, return \NULL{} and sets an
|
|
\exception{IndexError} exception.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, Py_ssize_t pos}
|
|
Like \cfunction{PyTuple_GetItem()}, but does no checking of its
|
|
arguments.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p,
|
|
Py_ssize_t low, Py_ssize_t high}
|
|
Take a slice of the tuple pointed to by \var{p} from \var{low} to
|
|
\var{high} and return it as a new tuple.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p,
|
|
Py_ssize_t pos, PyObject *o}
|
|
Insert a reference to object \var{o} at position \var{pos} of the
|
|
tuple pointed to by \var{p}. Return \code{0} on success.
|
|
\note{This function ``steals'' a reference to \var{o}.}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p,
|
|
Py_ssize_t pos, PyObject *o}
|
|
Like \cfunction{PyTuple_SetItem()}, but does no error checking, and
|
|
should \emph{only} be used to fill in brand new tuples. \note{This
|
|
function ``steals'' a reference to \var{o}.}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, Py_ssize_t newsize}
|
|
Can be used to resize a tuple. \var{newsize} will be the new length
|
|
of the tuple. Because tuples are \emph{supposed} to be immutable,
|
|
this should only be used if there is only one reference to the
|
|
object. Do \emph{not} use this if the tuple may already be known to
|
|
some other part of the code. The tuple will always grow or shrink
|
|
at the end. Think of this as destroying the old tuple and creating
|
|
a new one, only more efficiently. Returns \code{0} on success.
|
|
Client code should never assume that the resulting value of
|
|
\code{*\var{p}} will be the same as before calling this function.
|
|
If the object referenced by \code{*\var{p}} is replaced, the
|
|
original \code{*\var{p}} is destroyed. On failure, returns
|
|
\code{-1} and sets \code{*\var{p}} to \NULL{}, and raises
|
|
\exception{MemoryError} or
|
|
\exception{SystemError}.
|
|
\versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{List Objects \label{listObjects}}
|
|
|
|
\obindex{list}
|
|
\begin{ctypedesc}{PyListObject}
|
|
This subtype of \ctype{PyObject} represents a Python list object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyList_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python list
|
|
type. This is the same object as \code{list} and \code{types.ListType}
|
|
in the Python layer.\withsubitem{(in module types)}{\ttindex{ListType}}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
|
|
Return true if \var{p} is a list object or an instance of a
|
|
subtype of the list type.
|
|
\versionchanged[Allowed subtypes to be accepted]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_CheckExact}{PyObject *p}
|
|
Return true if \var{p} is a list object, but not an instance of a
|
|
subtype of the list type.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyList_New}{Py_ssize_t len}
|
|
Return a new list of length \var{len} on success, or \NULL{} on
|
|
failure.
|
|
\note{If \var{length} is greater than zero, the returned list object's
|
|
items are set to \code{NULL}. Thus you cannot use abstract
|
|
API functions such as \cfunction{PySequence_SetItem()}
|
|
or expose the object to Python code before setting all items to a
|
|
real object with \cfunction{PyList_SetItem()}.}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyList_Size}{PyObject *list}
|
|
Return the length of the list object in \var{list}; this is
|
|
equivalent to \samp{len(\var{list})} on a list object.
|
|
\bifuncindex{len}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyList_GET_SIZE}{PyObject *list}
|
|
Macro form of \cfunction{PyList_Size()} without error checking.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, Py_ssize_t index}
|
|
Return the object at position \var{pos} in the list pointed to by
|
|
\var{p}. The position must be positive, indexing from the end of the
|
|
list is not supported. If \var{pos} is out of bounds, return \NULL{}
|
|
and set an \exception{IndexError} exception.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, Py_ssize_t i}
|
|
Macro form of \cfunction{PyList_GetItem()} without error checking.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, Py_ssize_t index,
|
|
PyObject *item}
|
|
Set the item at index \var{index} in list to \var{item}. Return
|
|
\code{0} on success or \code{-1} on failure. \note{This function
|
|
``steals'' a reference to \var{item} and discards a reference to an
|
|
item already in the list at the affected position.}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, Py_ssize_t i,
|
|
PyObject *o}
|
|
Macro form of \cfunction{PyList_SetItem()} without error checking.
|
|
This is normally only used to fill in new lists where there is no
|
|
previous content.
|
|
\note{This function ``steals'' a reference to \var{item}, and,
|
|
unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a
|
|
reference to any item that it being replaced; any reference in
|
|
\var{list} at position \var{i} will be leaked.}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, Py_ssize_t index,
|
|
PyObject *item}
|
|
Insert the item \var{item} into list \var{list} in front of index
|
|
\var{index}. Return \code{0} if successful; return \code{-1} and
|
|
set an exception if unsuccessful. Analogous to
|
|
\code{\var{list}.insert(\var{index}, \var{item})}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
|
|
Append the object \var{item} at the end of list \var{list}.
|
|
Return \code{0} if successful; return \code{-1} and set an
|
|
exception if unsuccessful. Analogous to
|
|
\code{\var{list}.append(\var{item})}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
|
|
Py_ssize_t low, Py_ssize_t high}
|
|
Return a list of the objects in \var{list} containing the objects
|
|
\emph{between} \var{low} and \var{high}. Return \NULL{} and set
|
|
an exception if unsuccessful.
|
|
Analogous to \code{\var{list}[\var{low}:\var{high}]}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
|
|
Py_ssize_t low, Py_ssize_t high,
|
|
PyObject *itemlist}
|
|
Set the slice of \var{list} between \var{low} and \var{high} to the
|
|
contents of \var{itemlist}. Analogous to
|
|
\code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}.
|
|
The \var{itemlist} may be \NULL{}, indicating the assignment
|
|
of an empty list (slice deletion).
|
|
Return \code{0} on success, \code{-1} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
|
|
Sort the items of \var{list} in place. Return \code{0} on
|
|
success, \code{-1} on failure. This is equivalent to
|
|
\samp{\var{list}.sort()}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
|
|
Reverse the items of \var{list} in place. Return \code{0} on
|
|
success, \code{-1} on failure. This is the equivalent of
|
|
\samp{\var{list}.reverse()}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
|
|
Return a new tuple object containing the contents of \var{list};
|
|
equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Mapping Objects \label{mapObjects}}
|
|
|
|
\obindex{mapping}
|
|
|
|
|
|
\subsection{Dictionary Objects \label{dictObjects}}
|
|
|
|
\obindex{dictionary}
|
|
\begin{ctypedesc}{PyDictObject}
|
|
This subtype of \ctype{PyObject} represents a Python dictionary
|
|
object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyDict_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python
|
|
dictionary type. This is exposed to Python programs as
|
|
\code{dict} and \code{types.DictType}.
|
|
\withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
|
|
Return true if \var{p} is a dict object or an instance of a
|
|
subtype of the dict type.
|
|
\versionchanged[Allowed subtypes to be accepted]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_CheckExact}{PyObject *p}
|
|
Return true if \var{p} is a dict object, but not an instance of a
|
|
subtype of the dict type.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
|
|
Return a new empty dictionary, or \NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDictProxy_New}{PyObject *dict}
|
|
Return a proxy object for a mapping which enforces read-only
|
|
behavior. This is normally used to create a proxy to prevent
|
|
modification of the dictionary for non-dynamic class types.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p}
|
|
Empty an existing dictionary of all key-value pairs.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_Contains}{PyObject *p, PyObject *key}
|
|
Determine if dictionary \var{p} contains \var{key}. If an item
|
|
in \var{p} is matches \var{key}, return \code{1}, otherwise return
|
|
\code{0}. On error, return \code{-1}. This is equivalent to the
|
|
Python expression \samp{\var{key} in \var{p}}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p}
|
|
Return a new dictionary that contains the same key-value pairs as
|
|
\var{p}.
|
|
\versionadded{1.6}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key,
|
|
PyObject *val}
|
|
Insert \var{value} into the dictionary \var{p} with a key of
|
|
\var{key}. \var{key} must be hashable; if it isn't,
|
|
\exception{TypeError} will be raised.
|
|
Return \code{0} on success or \code{-1} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
|
|
const char *key,
|
|
PyObject *val}
|
|
Insert \var{value} into the dictionary \var{p} using \var{key} as a
|
|
key. \var{key} should be a \ctype{char*}. The key object is created
|
|
using \code{PyString_FromString(\var{key})}. Return \code{0} on
|
|
success or \code{-1} on failure.
|
|
\ttindex{PyString_FromString()}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key}
|
|
Remove the entry in dictionary \var{p} with key \var{key}.
|
|
\var{key} must be hashable; if it isn't, \exception{TypeError} is
|
|
raised. Return \code{0} on success or \code{-1} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key}
|
|
Remove the entry in dictionary \var{p} which has a key specified by
|
|
the string \var{key}. Return \code{0} on success or \code{-1} on
|
|
failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key}
|
|
Return the object from dictionary \var{p} which has a key
|
|
\var{key}. Return \NULL{} if the key \var{key} is not present, but
|
|
\emph{without} setting an exception.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, const char *key}
|
|
This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is
|
|
specified as a \ctype{char*}, rather than a \ctype{PyObject*}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p}
|
|
Return a \ctype{PyListObject} containing all the items from the
|
|
dictionary, as in the dictionary method \method{items()} (see the
|
|
\citetitle[../lib/lib.html]{Python Library Reference}).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p}
|
|
Return a \ctype{PyListObject} containing all the keys from the
|
|
dictionary, as in the dictionary method \method{keys()} (see the
|
|
\citetitle[../lib/lib.html]{Python Library Reference}).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p}
|
|
Return a \ctype{PyListObject} containing all the values from the
|
|
dictionary \var{p}, as in the dictionary method \method{values()}
|
|
(see the \citetitle[../lib/lib.html]{Python Library Reference}).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_ssize_t}{PyDict_Size}{PyObject *p}
|
|
Return the number of items in the dictionary. This is equivalent
|
|
to \samp{len(\var{p})} on a dictionary.\bifuncindex{len}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, Py_ssize_t *ppos,
|
|
PyObject **pkey, PyObject **pvalue}
|
|
Iterate over all key-value pairs in the dictionary \var{p}. The
|
|
\ctype{int} referred to by \var{ppos} must be initialized to
|
|
\code{0} prior to the first call to this function to start the
|
|
iteration; the function returns true for each pair in the
|
|
dictionary, and false once all pairs have been reported. The
|
|
parameters \var{pkey} and \var{pvalue} should either point to
|
|
\ctype{PyObject*} variables that will be filled in with each key and
|
|
value, respectively, or may be \NULL{}. Any references returned through
|
|
them are borrowed. \var{ppos} should not be altered during iteration.
|
|
Its value represents offsets within the internal dictionary structure,
|
|
and since the structure is sparse, the offsets are not consecutive.
|
|
|
|
For example:
|
|
|
|
\begin{verbatim}
|
|
PyObject *key, *value;
|
|
int pos = 0;
|
|
|
|
while (PyDict_Next(self->dict, &pos, &key, &value)) {
|
|
/* do something interesting with the values... */
|
|
...
|
|
}
|
|
\end{verbatim}
|
|
|
|
The dictionary \var{p} should not be mutated during iteration. It
|
|
is safe (since Python 2.1) to modify the values of the keys as you
|
|
iterate over the dictionary, but only so long as the set of keys
|
|
does not change. For example:
|
|
|
|
\begin{verbatim}
|
|
PyObject *key, *value;
|
|
int pos = 0;
|
|
|
|
while (PyDict_Next(self->dict, &pos, &key, &value)) {
|
|
int i = PyInt_AS_LONG(value) + 1;
|
|
PyObject *o = PyInt_FromLong(i);
|
|
if (o == NULL)
|
|
return -1;
|
|
if (PyDict_SetItem(self->dict, key, o) < 0) {
|
|
Py_DECREF(o);
|
|
return -1;
|
|
}
|
|
Py_DECREF(o);
|
|
}
|
|
\end{verbatim}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_Merge}{PyObject *a, PyObject *b, int override}
|
|
Iterate over mapping object \var{b} adding key-value pairs to dictionary
|
|
\var{a}.
|
|
\var{b} may be a dictionary, or any object supporting
|
|
\function{PyMapping_Keys()} and \function{PyObject_GetItem()}.
|
|
If \var{override} is true, existing pairs in \var{a} will
|
|
be replaced if a matching key is found in \var{b}, otherwise pairs
|
|
will only be added if there is not a matching key in \var{a}.
|
|
Return \code{0} on success or \code{-1} if an exception was
|
|
raised.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_Update}{PyObject *a, PyObject *b}
|
|
This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C,
|
|
or \code{\var{a}.update(\var{b})} in Python. Return \code{0} on
|
|
success or \code{-1} if an exception was raised.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_MergeFromSeq2}{PyObject *a, PyObject *seq2,
|
|
int override}
|
|
Update or merge into dictionary \var{a}, from the key-value pairs in
|
|
\var{seq2}. \var{seq2} must be an iterable object producing
|
|
iterable objects of length 2, viewed as key-value pairs. In case of
|
|
duplicate keys, the last wins if \var{override} is true, else the
|
|
first wins.
|
|
Return \code{0} on success or \code{-1} if an exception
|
|
was raised.
|
|
Equivalent Python (except for the return value):
|
|
|
|
\begin{verbatim}
|
|
def PyDict_MergeFromSeq2(a, seq2, override):
|
|
for key, value in seq2:
|
|
if override or key not in a:
|
|
a[key] = value
|
|
\end{verbatim}
|
|
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Other Objects \label{otherObjects}}
|
|
|
|
\subsection{File Objects \label{fileObjects}}
|
|
|
|
\obindex{file}
|
|
Python's built-in file objects are implemented entirely on the
|
|
\ctype{FILE*} support from the C standard library. This is an
|
|
implementation detail and may change in future releases of Python.
|
|
|
|
\begin{ctypedesc}{PyFileObject}
|
|
This subtype of \ctype{PyObject} represents a Python file object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyFile_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python file
|
|
type. This is exposed to Python programs as \code{file} and
|
|
\code{types.FileType}.
|
|
\withsubitem{(in module types)}{\ttindex{FileType}}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
|
|
Return true if its argument is a \ctype{PyFileObject} or a subtype
|
|
of \ctype{PyFileObject}.
|
|
\versionchanged[Allowed subtypes to be accepted]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p}
|
|
Return true if its argument is a \ctype{PyFileObject}, but not a
|
|
subtype of \ctype{PyFileObject}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode}
|
|
On success, return a new file object that is opened on the file
|
|
given by \var{filename}, with a file mode given by \var{mode}, where
|
|
\var{mode} has the same semantics as the standard C routine
|
|
\cfunction{fopen()}\ttindex{fopen()}. On failure, return \NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp,
|
|
char *name, char *mode,
|
|
int (*close)(FILE*)}
|
|
Create a new \ctype{PyFileObject} from the already-open standard C
|
|
file pointer, \var{fp}. The function \var{close} will be called
|
|
when the file should be closed. Return \NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyObject *p}
|
|
Return the file object associated with \var{p} as a \ctype{FILE*}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n}
|
|
Equivalent to \code{\var{p}.readline(\optional{\var{n}})}, this
|
|
function reads one line from the object \var{p}. \var{p} may be a
|
|
file object or any object with a \method{readline()} method. If
|
|
\var{n} is \code{0}, exactly one line is read, regardless of the
|
|
length of the line. If \var{n} is greater than \code{0}, no more
|
|
than \var{n} bytes will be read from the file; a partial line can be
|
|
returned. In both cases, an empty string is returned if the end of
|
|
the file is reached immediately. If \var{n} is less than \code{0},
|
|
however, one line is read regardless of length, but
|
|
\exception{EOFError} is raised if the end of the file is reached
|
|
immediately.
|
|
\withsubitem{(built-in exception)}{\ttindex{EOFError}}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p}
|
|
Return the name of the file specified by \var{p} as a string
|
|
object.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
|
|
Available on systems with \cfunction{setvbuf()}\ttindex{setvbuf()}
|
|
only. This should only be called immediately after file object
|
|
creation.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_Encoding}{PyFileObject *p, char *enc}
|
|
Set the file's encoding for Unicode output to \var{enc}. Return
|
|
1 on success and 0 on failure.
|
|
\versionadded{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag}
|
|
This function exists for internal use by the interpreter. Set the
|
|
\member{softspace} attribute of \var{p} to \var{newflag} and
|
|
\withsubitem{(file attribute)}{\ttindex{softspace}}return the
|
|
previous value. \var{p} does not have to be a file object for this
|
|
function to work properly; any object is supported (thought its only
|
|
interesting if the \member{softspace} attribute can be set). This
|
|
function clears any errors, and will return \code{0} as the previous
|
|
value if the attribute either does not exist or if there were errors
|
|
in retrieving it. There is no way to detect errors from this
|
|
function, but doing so should not be needed.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyObject *p,
|
|
int flags}
|
|
Write object \var{obj} to file object \var{p}. The only supported
|
|
flag for \var{flags} is
|
|
\constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW}; if given, the
|
|
\function{str()} of the object is written instead of the
|
|
\function{repr()}. Return \code{0} on success or \code{-1} on
|
|
failure; the appropriate exception will be set.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_WriteString}{const char *s, PyObject *p}
|
|
Write string \var{s} to file object \var{p}. Return \code{0} on
|
|
success or \code{-1} on failure; the appropriate exception will be
|
|
set.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Instance Objects \label{instanceObjects}}
|
|
|
|
\obindex{instance}
|
|
There are very few functions specific to instance objects.
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyInstance_Type}
|
|
Type object for class instances.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj}
|
|
Return true if \var{obj} is an instance.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class,
|
|
PyObject *arg,
|
|
PyObject *kw}
|
|
Create a new instance of a specific class. The parameters \var{arg}
|
|
and \var{kw} are used as the positional and keyword parameters to
|
|
the object's constructor.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class,
|
|
PyObject *dict}
|
|
Create a new instance of a specific class without calling its
|
|
constructor. \var{class} is the class of new object. The
|
|
\var{dict} parameter will be used as the object's \member{__dict__};
|
|
if \NULL{}, a new dictionary will be created for the instance.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Function Objects \label{function-objects}}
|
|
|
|
\obindex{function}
|
|
There are a few functions specific to Python functions.
|
|
|
|
\begin{ctypedesc}{PyFunctionObject}
|
|
The C structure used for functions.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyFunction_Type}
|
|
This is an instance of \ctype{PyTypeObject} and represents the
|
|
Python function type. It is exposed to Python programmers as
|
|
\code{types.FunctionType}.
|
|
\withsubitem{(in module types)}{\ttindex{MethodType}}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFunction_Check}{PyObject *o}
|
|
Return true if \var{o} is a function object (has type
|
|
\cdata{PyFunction_Type}). The parameter must not be \NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFunction_New}{PyObject *code,
|
|
PyObject *globals}
|
|
Return a new function object associated with the code object
|
|
\var{code}. \var{globals} must be a dictionary with the global
|
|
variables accessible to the function.
|
|
|
|
The function's docstring, name and \var{__module__} are retrieved
|
|
from the code object, the argument defaults and closure are set to
|
|
\NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFunction_GetCode}{PyObject *op}
|
|
Return the code object associated with the function object \var{op}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFunction_GetGlobals}{PyObject *op}
|
|
Return the globals dictionary associated with the function object
|
|
\var{op}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFunction_GetModule}{PyObject *op}
|
|
Return the \var{__module__} attribute of the function object \var{op}.
|
|
This is normally a string containing the module name, but can be set
|
|
to any other object by Python code.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFunction_GetDefaults}{PyObject *op}
|
|
Return the argument default values of the function object \var{op}.
|
|
This can be a tuple of arguments or \NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFunction_SetDefaults}{PyObject *op,
|
|
PyObject *defaults}
|
|
Set the argument default values for the function object \var{op}.
|
|
\var{defaults} must be \var{Py_None} or a tuple.
|
|
|
|
Raises \exception{SystemError} and returns \code{-1} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFunction_GetClosure}{PyObject *op}
|
|
Return the closure associated with the function object \var{op}.
|
|
This can be \NULL{} or a tuple of cell objects.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFunction_SetClosure}{PyObject *op,
|
|
PyObject *closure}
|
|
Set the closure associated with the function object \var{op}.
|
|
\var{closure} must be \var{Py_None} or a tuple of cell objects.
|
|
|
|
Raises \exception{SystemError} and returns \code{-1} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Method Objects \label{method-objects}}
|
|
|
|
\obindex{method}
|
|
There are some useful functions that are useful for working with
|
|
method objects.
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyMethod_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python method
|
|
type. This is exposed to Python programs as \code{types.MethodType}.
|
|
\withsubitem{(in module types)}{\ttindex{MethodType}}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o}
|
|
Return true if \var{o} is a method object (has type
|
|
\cdata{PyMethod_Type}). The parameter must not be \NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func,
|
|
PyObject *self, PyObject *class}
|
|
Return a new method object, with \var{func} being any callable
|
|
object; this is the function that will be called when the method is
|
|
called. If this method should be bound to an instance, \var{self}
|
|
should be the instance and \var{class} should be the class of
|
|
\var{self}, otherwise \var{self} should be \NULL{} and \var{class}
|
|
should be the class which provides the unbound method..
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMethod_Class}{PyObject *meth}
|
|
Return the class object from which the method \var{meth} was
|
|
created; if this was created from an instance, it will be the class
|
|
of the instance.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMethod_GET_CLASS}{PyObject *meth}
|
|
Macro version of \cfunction{PyMethod_Class()} which avoids error
|
|
checking.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMethod_Function}{PyObject *meth}
|
|
Return the function object associated with the method \var{meth}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMethod_GET_FUNCTION}{PyObject *meth}
|
|
Macro version of \cfunction{PyMethod_Function()} which avoids error
|
|
checking.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth}
|
|
Return the instance associated with the method \var{meth} if it is
|
|
bound, otherwise return \NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth}
|
|
Macro version of \cfunction{PyMethod_Self()} which avoids error
|
|
checking.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Module Objects \label{moduleObjects}}
|
|
|
|
\obindex{module}
|
|
There are only a few functions special to module objects.
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyModule_Type}
|
|
This instance of \ctype{PyTypeObject} represents the Python module
|
|
type. This is exposed to Python programs as
|
|
\code{types.ModuleType}.
|
|
\withsubitem{(in module types)}{\ttindex{ModuleType}}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p}
|
|
Return true if \var{p} is a module object, or a subtype of a module
|
|
object.
|
|
\versionchanged[Allowed subtypes to be accepted]{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p}
|
|
Return true if \var{p} is a module object, but not a subtype of
|
|
\cdata{PyModule_Type}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyModule_New}{const char *name}
|
|
Return a new module object with the \member{__name__} attribute set
|
|
to \var{name}. Only the module's \member{__doc__} and
|
|
\member{__name__} attributes are filled in; the caller is
|
|
responsible for providing a \member{__file__} attribute.
|
|
\withsubitem{(module attribute)}{
|
|
\ttindex{__name__}\ttindex{__doc__}\ttindex{__file__}}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module}
|
|
Return the dictionary object that implements \var{module}'s
|
|
namespace; this object is the same as the \member{__dict__}
|
|
attribute of the module object. This function never fails.
|
|
\withsubitem{(module attribute)}{\ttindex{__dict__}}
|
|
It is recommended extensions use other \cfunction{PyModule_*()}
|
|
and \cfunction{PyObject_*()} functions rather than directly
|
|
manipulate a module's \member{__dict__}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module}
|
|
Return \var{module}'s \member{__name__} value. If the module does
|
|
not provide one, or if it is not a string, \exception{SystemError}
|
|
is raised and \NULL{} is returned.
|
|
\withsubitem{(module attribute)}{\ttindex{__name__}}
|
|
\withsubitem{(built-in exception)}{\ttindex{SystemError}}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module}
|
|
Return the name of the file from which \var{module} was loaded using
|
|
\var{module}'s \member{__file__} attribute. If this is not defined,
|
|
or if it is not a string, raise \exception{SystemError} and return
|
|
\NULL{}.
|
|
\withsubitem{(module attribute)}{\ttindex{__file__}}
|
|
\withsubitem{(built-in exception)}{\ttindex{SystemError}}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module,
|
|
const char *name, PyObject *value}
|
|
Add an object to \var{module} as \var{name}. This is a convenience
|
|
function which can be used from the module's initialization
|
|
function. This steals a reference to \var{value}. Return
|
|
\code{-1} on error, \code{0} on success.
|
|
\versionadded{2.0}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module,
|
|
const char *name, long value}
|
|
Add an integer constant to \var{module} as \var{name}. This
|
|
convenience function can be used from the module's initialization
|
|
function. Return \code{-1} on error, \code{0} on success.
|
|
\versionadded{2.0}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module,
|
|
const char *name, const char *value}
|
|
Add a string constant to \var{module} as \var{name}. This
|
|
convenience function can be used from the module's initialization
|
|
function. The string \var{value} must be null-terminated. Return
|
|
\code{-1} on error, \code{0} on success.
|
|
\versionadded{2.0}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Iterator Objects \label{iterator-objects}}
|
|
|
|
Python provides two general-purpose iterator objects. The first, a
|
|
sequence iterator, works with an arbitrary sequence supporting the
|
|
\method{__getitem__()} method. The second works with a callable
|
|
object and a sentinel value, calling the callable for each item in the
|
|
sequence, and ending the iteration when the sentinel value is
|
|
returned.
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PySeqIter_Type}
|
|
Type object for iterator objects returned by
|
|
\cfunction{PySeqIter_New()} and the one-argument form of the
|
|
\function{iter()} built-in function for built-in sequence types.
|
|
\versionadded{2.2}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySeqIter_Check}{op}
|
|
Return true if the type of \var{op} is \cdata{PySeqIter_Type}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySeqIter_New}{PyObject *seq}
|
|
Return an iterator that works with a general sequence object,
|
|
\var{seq}. The iteration ends when the sequence raises
|
|
\exception{IndexError} for the subscripting operation.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyCallIter_Type}
|
|
Type object for iterator objects returned by
|
|
\cfunction{PyCallIter_New()} and the two-argument form of the
|
|
\function{iter()} built-in function.
|
|
\versionadded{2.2}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyCallIter_Check}{op}
|
|
Return true if the type of \var{op} is \cdata{PyCallIter_Type}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyCallIter_New}{PyObject *callable,
|
|
PyObject *sentinel}
|
|
Return a new iterator. The first parameter, \var{callable}, can be
|
|
any Python callable object that can be called with no parameters;
|
|
each call to it should return the next item in the iteration. When
|
|
\var{callable} returns a value equal to \var{sentinel}, the
|
|
iteration will be terminated.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Descriptor Objects \label{descriptor-objects}}
|
|
|
|
``Descriptors'' are objects that describe some attribute of an object.
|
|
They are found in the dictionary of type objects.
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyProperty_Type}
|
|
The type object for the built-in descriptor types.
|
|
\versionadded{2.2}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type,
|
|
struct PyGetSetDef *getset}
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type,
|
|
struct PyMemberDef *meth}
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type,
|
|
struct PyMethodDef *meth}
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDescr_NewWrapper}{PyTypeObject *type,
|
|
struct wrapperbase *wrapper,
|
|
void *wrapped}
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDescr_NewClassMethod}{PyTypeObject *type,
|
|
PyMethodDef *method}
|
|
\versionadded{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDescr_IsData}{PyObject *descr}
|
|
Return true if the descriptor objects \var{descr} describes a data
|
|
attribute, or false if it describes a method. \var{descr} must be a
|
|
descriptor object; there is no error checking.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyWrapper_New}{PyObject *, PyObject *}
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Slice Objects \label{slice-objects}}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PySlice_Type}
|
|
The type object for slice objects. This is the same as
|
|
\code{slice} and \code{types.SliceType}.
|
|
\withsubitem{(in module types)}{\ttindex{SliceType}}
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob}
|
|
Return true if \var{ob} is a slice object; \var{ob} must not be
|
|
\NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySlice_New}{PyObject *start, PyObject *stop,
|
|
PyObject *step}
|
|
Return a new slice object with the given values. The \var{start},
|
|
\var{stop}, and \var{step} parameters are used as the values of the
|
|
slice object attributes of the same names. Any of the values may be
|
|
\NULL{}, in which case the \code{None} will be used for the
|
|
corresponding attribute. Return \NULL{} if the new object could
|
|
not be allocated.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, Py_ssize_t length,
|
|
Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step}
|
|
Retrieve the start, stop and step indices from the slice object
|
|
\var{slice}, assuming a sequence of length \var{length}. Treats
|
|
indices greater than \var{length} as errors.
|
|
|
|
Returns 0 on success and -1 on error with no exception set (unless one
|
|
of the indices was not \constant{None} and failed to be converted to
|
|
an integer, in which case -1 is returned with an exception set).
|
|
|
|
You probably do not want to use this function. If you want to use
|
|
slice objects in versions of Python prior to 2.3, you would probably
|
|
do well to incorporate the source of \cfunction{PySlice_GetIndicesEx},
|
|
suitably renamed, in the source of your extension.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySlice_GetIndicesEx}{PySliceObject *slice, Py_ssize_t length,
|
|
Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step,
|
|
Py_ssize_t *slicelength}
|
|
Usable replacement for \cfunction{PySlice_GetIndices}. Retrieve the
|
|
start, stop, and step indices from the slice object \var{slice}
|
|
assuming a sequence of length \var{length}, and store the length of
|
|
the slice in \var{slicelength}. Out of bounds indices are clipped in
|
|
a manner consistent with the handling of normal slices.
|
|
|
|
Returns 0 on success and -1 on error with exception set.
|
|
|
|
\versionadded{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Weak Reference Objects \label{weakref-objects}}
|
|
|
|
Python supports \emph{weak references} as first-class objects. There
|
|
are two specific object types which directly implement weak
|
|
references. The first is a simple reference object, and the second
|
|
acts as a proxy for the original object as much as it can.
|
|
|
|
\begin{cfuncdesc}{int}{PyWeakref_Check}{ob}
|
|
Return true if \var{ob} is either a reference or proxy object.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyWeakref_CheckRef}{ob}
|
|
Return true if \var{ob} is a reference object.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyWeakref_CheckProxy}{ob}
|
|
Return true if \var{ob} is a proxy object.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyWeakref_NewRef}{PyObject *ob,
|
|
PyObject *callback}
|
|
Return a weak reference object for the object \var{ob}. This will
|
|
always return a new reference, but is not guaranteed to create a new
|
|
object; an existing reference object may be returned. The second
|
|
parameter, \var{callback}, can be a callable object that receives
|
|
notification when \var{ob} is garbage collected; it should accept a
|
|
single parameter, which will be the weak reference object itself.
|
|
\var{callback} may also be \code{None} or \NULL{}. If \var{ob}
|
|
is not a weakly-referencable object, or if \var{callback} is not
|
|
callable, \code{None}, or \NULL{}, this will return \NULL{} and
|
|
raise \exception{TypeError}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyWeakref_NewProxy}{PyObject *ob,
|
|
PyObject *callback}
|
|
Return a weak reference proxy object for the object \var{ob}. This
|
|
will always return a new reference, but is not guaranteed to create
|
|
a new object; an existing proxy object may be returned. The second
|
|
parameter, \var{callback}, can be a callable object that receives
|
|
notification when \var{ob} is garbage collected; it should accept a
|
|
single parameter, which will be the weak reference object itself.
|
|
\var{callback} may also be \code{None} or \NULL{}. If \var{ob} is not
|
|
a weakly-referencable object, or if \var{callback} is not callable,
|
|
\code{None}, or \NULL{}, this will return \NULL{} and raise
|
|
\exception{TypeError}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyWeakref_GetObject}{PyObject *ref}
|
|
Return the referenced object from a weak reference, \var{ref}. If
|
|
the referent is no longer live, returns \code{None}.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyWeakref_GET_OBJECT}{PyObject *ref}
|
|
Similar to \cfunction{PyWeakref_GetObject()}, but implemented as a
|
|
macro that does no error checking.
|
|
\versionadded{2.2}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{CObjects \label{cObjects}}
|
|
|
|
\obindex{CObject}
|
|
Refer to \emph{Extending and Embedding the Python Interpreter},
|
|
section~1.12, ``Providing a C API for an Extension Module,'' for more
|
|
information on using these objects.
|
|
|
|
|
|
\begin{ctypedesc}{PyCObject}
|
|
This subtype of \ctype{PyObject} represents an opaque value, useful
|
|
for C extension modules who need to pass an opaque value (as a
|
|
\ctype{void*} pointer) through Python code to other C code. It is
|
|
often used to make a C function pointer defined in one module
|
|
available to other modules, so the regular import mechanism can be
|
|
used to access C APIs defined in dynamically loaded modules.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyCObject_Check}{PyObject *p}
|
|
Return true if its argument is a \ctype{PyCObject}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj,
|
|
void (*destr)(void *)}
|
|
Create 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}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj,
|
|
void* desc, void (*destr)(void *, void *)}
|
|
Create a \ctype{PyCObject} from the \ctype{void *}\var{cobj}. The
|
|
\var{destr} function will be called when the object is reclaimed.
|
|
The \var{desc} argument can be used to pass extra callback data for
|
|
the destructor function.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void*}{PyCObject_AsVoidPtr}{PyObject* self}
|
|
Return the object \ctype{void *} that the \ctype{PyCObject}
|
|
\var{self} was created with.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void*}{PyCObject_GetDesc}{PyObject* self}
|
|
Return the description \ctype{void *} that the \ctype{PyCObject}
|
|
\var{self} was created with.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyCObject_SetVoidPtr}{PyObject* self, void* cobj}
|
|
Set the void pointer inside \var{self} to \var{cobj}.
|
|
The \ctype{PyCObject} must not have an associated destructor.
|
|
Return true on success, false on failure.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Cell Objects \label{cell-objects}}
|
|
|
|
``Cell'' objects are used to implement variables referenced by
|
|
multiple scopes. For each such variable, a cell object is created to
|
|
store the value; the local variables of each stack frame that
|
|
references the value contains a reference to the cells from outer
|
|
scopes which also use that variable. When the value is accessed, the
|
|
value contained in the cell is used instead of the cell object
|
|
itself. This de-referencing of the cell object requires support from
|
|
the generated byte-code; these are not automatically de-referenced
|
|
when accessed. Cell objects are not likely to be useful elsewhere.
|
|
|
|
\begin{ctypedesc}{PyCellObject}
|
|
The C structure used for cell objects.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyCell_Type}
|
|
The type object corresponding to cell objects.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyCell_Check}{ob}
|
|
Return true if \var{ob} is a cell object; \var{ob} must not be
|
|
\NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyCell_New}{PyObject *ob}
|
|
Create and return a new cell object containing the value \var{ob}.
|
|
The parameter may be \NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyCell_Get}{PyObject *cell}
|
|
Return the contents of the cell \var{cell}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyCell_GET}{PyObject *cell}
|
|
Return the contents of the cell \var{cell}, but without checking
|
|
that \var{cell} is non-\NULL{} and a cell object.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyCell_Set}{PyObject *cell, PyObject *value}
|
|
Set the contents of the cell object \var{cell} to \var{value}. This
|
|
releases the reference to any current content of the cell.
|
|
\var{value} may be \NULL{}. \var{cell} must be non-\NULL{}; if it is
|
|
not a cell object, \code{-1} will be returned. On success, \code{0}
|
|
will be returned.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyCell_SET}{PyObject *cell, PyObject *value}
|
|
Sets the value of the cell object \var{cell} to \var{value}. No
|
|
reference counts are adjusted, and no checks are made for safety;
|
|
\var{cell} must be non-\NULL{} and must be a cell object.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Generator Objects \label{gen-objects}}
|
|
|
|
Generator objects are what Python uses to implement generator iterators.
|
|
They are normally created by iterating over a function that yields values,
|
|
rather than explicitly calling \cfunction{PyGen_New}.
|
|
|
|
\begin{ctypedesc}{PyGenObject}
|
|
The C structure used for generator objects.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyGen_Type}
|
|
The type object corresponding to generator objects
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyGen_Check}{ob}
|
|
Return true if \var{ob} is a generator object; \var{ob} must not be
|
|
\NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyGen_CheckExact}{ob}
|
|
Return true if \var{ob}'s type is \var{PyGen_Type}
|
|
is a generator object; \var{ob} must not be
|
|
\NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyGen_New}{PyFrameObject *frame}
|
|
Create and return a new generator object based on the \var{frame} object.
|
|
A reference to \var{frame} is stolen by this function.
|
|
The parameter must not be \NULL{}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{DateTime Objects \label{datetime-objects}}
|
|
|
|
Various date and time objects are supplied by the \module{datetime}
|
|
module. Before using any of these functions, the header file
|
|
\file{datetime.h} must be included in your source (note that this is
|
|
not include by \file{Python.h}), and macro \cfunction{PyDateTime_IMPORT()}
|
|
must be invoked. The macro arranges to put a pointer to a C structure
|
|
in a static variable \code{PyDateTimeAPI}, which is used by the following
|
|
macros.
|
|
|
|
Type-check macros:
|
|
|
|
\begin{cfuncdesc}{int}{PyDate_Check}{PyObject *ob}
|
|
Return true if \var{ob} is of type \cdata{PyDateTime_DateType} or
|
|
a subtype of \cdata{PyDateTime_DateType}. \var{ob} must not be
|
|
\NULL{}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDate_CheckExact}{PyObject *ob}
|
|
Return true if \var{ob} is of type \cdata{PyDateTime_DateType}.
|
|
\var{ob} must not be \NULL{}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_Check}{PyObject *ob}
|
|
Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType} or
|
|
a subtype of \cdata{PyDateTime_DateTimeType}. \var{ob} must not be
|
|
\NULL{}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_CheckExact}{PyObject *ob}
|
|
Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType}.
|
|
\var{ob} must not be \NULL{}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTime_Check}{PyObject *ob}
|
|
Return true if \var{ob} is of type \cdata{PyDateTime_TimeType} or
|
|
a subtype of \cdata{PyDateTime_TimeType}. \var{ob} must not be
|
|
\NULL{}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTime_CheckExact}{PyObject *ob}
|
|
Return true if \var{ob} is of type \cdata{PyDateTime_TimeType}.
|
|
\var{ob} must not be \NULL{}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDelta_Check}{PyObject *ob}
|
|
Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType} or
|
|
a subtype of \cdata{PyDateTime_DeltaType}. \var{ob} must not be
|
|
\NULL{}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDelta_CheckExact}{PyObject *ob}
|
|
Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType}.
|
|
\var{ob} must not be \NULL{}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTZInfo_Check}{PyObject *ob}
|
|
Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType} or
|
|
a subtype of \cdata{PyDateTime_TZInfoType}. \var{ob} must not be
|
|
\NULL{}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTZInfo_CheckExact}{PyObject *ob}
|
|
Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType}.
|
|
\var{ob} must not be \NULL{}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
Macros to create objects:
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDate_FromDate}{int year, int month, int day}
|
|
Return a \code{datetime.date} object with the specified year, month
|
|
and day.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDateTime_FromDateAndTime}{int year, int month,
|
|
int day, int hour, int minute, int second, int usecond}
|
|
Return a \code{datetime.datetime} object with the specified year, month,
|
|
day, hour, minute, second and microsecond.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyTime_FromTime}{int hour, int minute,
|
|
int second, int usecond}
|
|
Return a \code{datetime.time} object with the specified hour, minute,
|
|
second and microsecond.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDelta_FromDSU}{int days, int seconds,
|
|
int useconds}
|
|
Return a \code{datetime.timedelta} object representing the given number
|
|
of days, seconds and microseconds. Normalization is performed so that
|
|
the resulting number of microseconds and seconds lie in the ranges
|
|
documented for \code{datetime.timedelta} objects.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
Macros to extract fields from date objects. The argument must be an
|
|
instance of \cdata{PyDateTime_Date}, including subclasses (such as
|
|
\cdata{PyDateTime_DateTime}). The argument must not be \NULL{}, and
|
|
the type is not checked:
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_GET_YEAR}{PyDateTime_Date *o}
|
|
Return the year, as a positive int.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_GET_MONTH}{PyDateTime_Date *o}
|
|
Return the month, as an int from 1 through 12.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_GET_DAY}{PyDateTime_Date *o}
|
|
Return the day, as an int from 1 through 31.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
Macros to extract fields from datetime objects. The argument must be an
|
|
instance of \cdata{PyDateTime_DateTime}, including subclasses.
|
|
The argument must not be \NULL{}, and the type is not checked:
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_HOUR}{PyDateTime_DateTime *o}
|
|
Return the hour, as an int from 0 through 23.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MINUTE}{PyDateTime_DateTime *o}
|
|
Return the minute, as an int from 0 through 59.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_SECOND}{PyDateTime_DateTime *o}
|
|
Return the second, as an int from 0 through 59.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MICROSECOND}{PyDateTime_DateTime *o}
|
|
Return the microsecond, as an int from 0 through 999999.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
Macros to extract fields from time objects. The argument must be an
|
|
instance of \cdata{PyDateTime_Time}, including subclasses.
|
|
The argument must not be \NULL{}, and the type is not checked:
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_HOUR}{PyDateTime_Time *o}
|
|
Return the hour, as an int from 0 through 23.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MINUTE}{PyDateTime_Time *o}
|
|
Return the minute, as an int from 0 through 59.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_SECOND}{PyDateTime_Time *o}
|
|
Return the second, as an int from 0 through 59.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MICROSECOND}{PyDateTime_Time *o}
|
|
Return the microsecond, as an int from 0 through 999999.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
Macros for the convenience of modules implementing the DB API:
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDateTime_FromTimestamp}{PyObject *args}
|
|
Create and return a new \code{datetime.datetime} object given an argument
|
|
tuple suitable for passing to \code{datetime.datetime.fromtimestamp()}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDate_FromTimestamp}{PyObject *args}
|
|
Create and return a new \code{datetime.date} object given an argument
|
|
tuple suitable for passing to \code{datetime.date.fromtimestamp()}.
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Set Objects \label{setObjects}}
|
|
\sectionauthor{Raymond D. Hettinger}{python@rcn.com}
|
|
|
|
\obindex{set}
|
|
\obindex{frozenset}
|
|
\versionadded{2.5}
|
|
|
|
This section details the public API for \class{set} and \class{frozenset}
|
|
objects. Any functionality not listed below is best accessed using the
|
|
either the abstract object protocol (including
|
|
\cfunction{PyObject_CallMethod()}, \cfunction{PyObject_RichCompareBool()},
|
|
\cfunction{PyObject_Hash()}, \cfunction{PyObject_Repr()},
|
|
\cfunction{PyObject_IsTrue()}, \cfunction{PyObject_Print()}, and
|
|
\cfunction{PyObject_GetIter()})
|
|
or the abstract number protocol (including
|
|
\cfunction{PyNumber_Add()}, \cfunction{PyNumber_Subtract()},
|
|
\cfunction{PyNumber_Or()}, \cfunction{PyNumber_Xor()},
|
|
\cfunction{PyNumber_InPlaceAdd()}, \cfunction{PyNumber_InPlaceSubtract()},
|
|
\cfunction{PyNumber_InPlaceOr()}, and \cfunction{PyNumber_InPlaceXor()}).
|
|
|
|
\begin{ctypedesc}{PySetObject}
|
|
This subtype of \ctype{PyObject} is used to hold the internal data for
|
|
both \class{set} and \class{frozenset} objects. It is like a
|
|
\ctype{PyDictObject} in that it is a fixed size for small sets
|
|
(much like tuple storage) and will point to a separate, variable sized
|
|
block of memory for medium and large sized sets (much like list storage).
|
|
None of the fields of this structure should be considered public and
|
|
are subject to change. All access should be done through the
|
|
documented API rather than by manipulating the values in the structure.
|
|
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PySet_Type}
|
|
This is an instance of \ctype{PyTypeObject} representing the Python
|
|
\class{set} type.
|
|
\end{cvardesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyFrozenSet_Type}
|
|
This is an instance of \ctype{PyTypeObject} representing the Python
|
|
\class{frozenset} type.
|
|
\end{cvardesc}
|
|
|
|
|
|
The following type check macros work on pointers to any Python object.
|
|
Likewise, the constructor functions work with any iterable Python object.
|
|
|
|
\begin{cfuncdesc}{int}{PyAnySet_Check}{PyObject *p}
|
|
Return true if \var{p} is a \class{set} object, a \class{frozenset}
|
|
object, or an instance of a subtype.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyAnySet_CheckExact}{PyObject *p}
|
|
Return true if \var{p} is a \class{set} object or a \class{frozenset}
|
|
object but not an instance of a subtype.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFrozenSet_CheckExact}{PyObject *p}
|
|
Return true if \var{p} is a \class{frozenset} object
|
|
but not an instance of a subtype.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySet_New}{PyObject *iterable}
|
|
Return a new \class{set} containing objects returned by the
|
|
\var{iterable}. The \var{iterable} may be \NULL{} to create a
|
|
new empty set. Return the new set on success or \NULL{} on
|
|
failure. Raise \exception{TypeError} if \var{iterable} is
|
|
not actually iterable. The constructor is also useful for
|
|
copying a set (\code{c=set(s)}).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFrozenSet_New}{PyObject *iterable}
|
|
Return a new \class{frozenset} containing objects returned by the
|
|
\var{iterable}. The \var{iterable} may be \NULL{} to create a
|
|
new empty frozenset. Return the new set on success or \NULL{} on
|
|
failure. Raise \exception{TypeError} if \var{iterable} is
|
|
not actually iterable.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
The following functions and macros are available for instances of
|
|
\class{set} or \class{frozenset} or instances of their subtypes.
|
|
|
|
\begin{cfuncdesc}{int}{PySet_Size}{PyObject *anyset}
|
|
Return the length of a \class{set} or \class{frozenset} object.
|
|
Equivalent to \samp{len(\var{anyset})}. Raises a
|
|
\exception{PyExc_SystemError} if \var{anyset} is not a \class{set},
|
|
\class{frozenset}, or an instance of a subtype.
|
|
\bifuncindex{len}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySet_GET_SIZE}{PyObject *anyset}
|
|
Macro form of \cfunction{PySet_Size()} without error checking.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySet_Contains}{PyObject *anyset, PyObject *key}
|
|
Return 1 if found, 0 if not found, and -1 if an error is
|
|
encountered. Unlike the Python \method{__contains__()} method, this
|
|
function does not automatically convert unhashable sets into temporary
|
|
frozensets. Raise a \exception{TypeError} if the \var{key} is unhashable.
|
|
Raise \exception{PyExc_SystemError} if \var{anyset} is not a \class{set},
|
|
\class{frozenset}, or an instance of a subtype.
|
|
\end{cfuncdesc}
|
|
|
|
The following functions are available for instances of \class{set} or
|
|
its subtypes but not for instances of \class{frozenset} or its subtypes.
|
|
|
|
\begin{cfuncdesc}{int}{PySet_Add}{PyObject *set, PyObject *key}
|
|
Add \var{key} to a \class{set} instance. Does not apply to
|
|
\class{frozenset} instances. Return 0 on success or -1 on failure.
|
|
Raise a \exception{TypeError} if the \var{key} is unhashable.
|
|
Raise a \exception{MemoryError} if there is no room to grow.
|
|
Raise a \exception{SystemError} if \var{set} is an not an instance
|
|
of \class{set} or its subtype.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySet_Discard}{PyObject *set, PyObject *key}
|
|
Return 1 if found and removed, 0 if not found (no action taken),
|
|
and -1 if an error is encountered. Does not raise \exception{KeyError}
|
|
for missing keys. Raise a \exception{TypeError} if the \var{key} is
|
|
unhashable. Unlike the Python \method{discard()} method, this function
|
|
does not automatically convert unhashable sets into temporary frozensets.
|
|
Raise \exception{PyExc_SystemError} if \var{set} is an not an instance
|
|
of \class{set} or its subtype.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySet_Pop}{PyObject *set}
|
|
Return a new reference to an arbitrary object in the \var{set},
|
|
and removes the object from the \var{set}. Return \NULL{} on
|
|
failure. Raise \exception{KeyError} if the set is empty.
|
|
Raise a \exception{SystemError} if \var{set} is an not an instance
|
|
of \class{set} or its subtype.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySet_Clear}{PyObject *set}
|
|
Empty an existing set of all elements.
|
|
\end{cfuncdesc}
|