izzy/cpython
0
0
Fork 0
mirror of https://github.com/izzy2lost/cpython.git synced 2026-06-19 01:16:18 -07:00
Code Issues Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Greentwip
2020-11-03 11:10:27 -07:00
parent 7859d26485
commit bf48f47304
4147 changed files with 1783608 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.bzrignore
+42
View File
@@ -0,0 +1,42 @@
´.purify
autom4te.cache
config.log
config.cache
config.status
config.status.lineno
db_home
Makefile
buildno
python
build
Makefile.pre
platform
pybuilddir.txt
pyconfig.h
libpython*.a
libpython*.so*
python.exe
python-gdb.py
reflog.txt
tags
TAGS
.gdb_history
Doc/tools/sphinx
Doc/tools/jinja
Doc/tools/jinja2
Doc/tools/pygments
Doc/tools/docutils
Misc/python.pc
Modules/Setup
Modules/Setup.config
Modules/Setup.local
Modules/config.c
Modules/ld_so_aix
Parser/pgen
Lib/test/data/*
Lib/lib2to3/Grammar*.pickle
Lib/lib2to3/PatternGrammar*.pickle
__pycache__
.coverage
coverage/*
htmlcov/*
.gitignore
+74
View File
@@ -348,3 +348,77 @@ MigrationBackup/
# Ionide (cross platform F# VS Code tools) working folder
.ionide/
*.cover
*.o
*.orig
*.pyc
*.pyd
*.pyo
*.rej
*.swp
*~
.gdb_history
Doc/build/
Doc/tools/docutils/
Doc/tools/jinja/
Doc/tools/jinja2/
Doc/tools/pygments/
Doc/tools/sphinx/
Lib/lib2to3/*.pickle
Lib/test/data/*
Lib/_sysconfigdata.py
Lib/plat-mac/errors.rsrc.df.rsrc
Makefile
Makefile.pre
Misc/python.pc
Misc/python-config.sh
Modules/Setup
Modules/Setup.config
Modules/Setup.local
Modules/config.c
Modules/ld_so_aix
Modules/_freeze_importlib
Modules/_testembed
PCbuild/*.bsc
PCbuild/*.dll
PCbuild/*.exe
PCbuild/*.exp
PCbuild/*.lib
PCbuild/*.ncb
PCbuild/*.o
PCbuild/*.pdb
PCbuild/Win32-temp-*
PCbuild/amd64/
.purify
Parser/pgen
__pycache__
autom4te.cache
build/
buildno
config.cache
config.log
config.status
config.status.lineno
core
db_home
config.log
config.status
libpython*.a
libpython*.so*
platform
pybuilddir.txt
pyconfig.h
python
python-config
python-config.py
python.exe
python-gdb.py
python.exe-gdb.py
reflog.txt
.svn/
tags
TAGS
.coverage
coverage/
htmlcov/
.hgeol
+49
View File
@@ -0,0 +1,49 @@
[patterns]
# Non human-editable files are binary
**.dsp = BIN
**.dsw = BIN
**.mk = BIN
**.sln = BIN
**.vcproj = BIN
**.vsprops = BIN
**.vcxproj = BIN
**.vcxproj.filters = BIN
**.aif = BIN
**.aifc = BIN
**.aiff = BIN
**.au = BIN
**.bmp = BIN
**.db = BIN
**.exe = BIN
**.icns = BIN
**.gif = BIN
**.ico = BIN
**.info = BIN
**.jpg = BIN
**.pck = BIN
**.png = BIN
**.psd = BIN
**.tar = BIN
**.wav = BIN
**.whl = BIN
**.xar = BIN
**.zip = BIN
Lib/test/cjkencodings/* = BIN
Lib/test/decimaltestdata/*.decTest = BIN
Lib/test/sndhdrdata/sndhdr.* = BIN
Lib/test/test_email/data/msg_26.txt = BIN
Lib/test/xmltestdata/* = BIN
Lib/venv/scripts/nt/* = BIN
# All other files (which presumably are human-editable) are "native".
# This must be the last rule!
** = native
[repository]
native = LF
.hgignore
+105
View File
@@ -0,0 +1,105 @@
.gdb_history
.purify
.svn/
^.idea/
.DS_Store
Makefile$
Makefile.pre$
TAGS$
autom4te.cache$
^build/
^Doc/build/
Debug/
Release/
AppPackages/
buildno$
config.cache
config.log
config.status
config.status.lineno
db_home
platform$
pyconfig.h$
python$
python.exe$
python-config$
python-config.py$
reflog.txt$
tags$
Lib/plat-mac/errors.rsrc.df.rsrc
Doc/tools/sphinx/
Doc/tools/docutils/
Doc/tools/jinja/
Doc/tools/jinja2/
Doc/tools/pygments/
Misc/python.pc
Misc/python-config.sh$
Modules/Setup$
Modules/Setup.config
Modules/Setup.local
Modules/config.c
Modules/ld_so_aix$
Parser/pgen$
^lcov-report/
^core
^python-gdb.py
^python.exe-gdb.py
^pybuilddir.txt
syntax: glob
libpython*.a
libpython*.so*
*.swp
*.o
*.pyc
*.pyo
*.pyd
*.cover
*~
Lib/lib2to3/*.pickle
Lib/test/data/*
Misc/*.wpu
PC/python_nt*.h
PC/pythonnt_rc*.h
PC/*.obj
PC/*.exe
PC/*/*.exe
PC/*/*.exp
PC/*/*.lib
PC/*/*.bsc
PC/*/*.dll
PC/*/*.pdb
PC/*/*.user
PC/*/*.ncb
PC/*/*.suo
PC/*/Win32-temp-*
PC/*/x64-temp-*
PC/*/amd64
PCbuild/*.exe
PCbuild/*.dll
PCbuild/*.pdb
PCbuild/*.lib
PCbuild/*.exp
PCbuild/*.o
PCbuild/*.ncb
PCbuild/*.bsc
PCbuild/*.user
PCbuild/*.suo
PCbuild/*.*sdf
PCbuild/Win32-temp-*
PCbuild/x64-temp-*
PCbuild/amd64
PCbuild/ipch
Tools/unicode/build/
Tools/unicode/MAPPINGS/
BuildLog.htm
__pycache__
Modules/_freeze_importlib
Modules/_testembed
.coverage
coverage/
htmlcov/
*.gcda
*.gcno
*.gcov
coverage.info
.hgtags
+131
View File
@@ -0,0 +1,131 @@
64cc5439e10a6fdf984effaf0141e94fa4cc1004 v0.9.8
78a7ed6953025e7ecdde9585099b01a6ae40b76a v0.9.9
b15b8cc9b8d10e0352a0b8b7e8d51fa309db6df3 v1.0.1
0326b5d61445ee3a8d3de28119f9652cb72d2e3f v1.0.2
832615ec07646e310c85316b8ba6bc9b17ad3547 v1.1
9895475d18c7b5f32adaf78f71886ae041e4d10c v1.1.1
16eb4c51ee97169046340998e850a63c65225b0a v1.2b1
b45c688756d04fb84d4a0d518fc3d7e3cb25fa8d v1.2b2
9e82daf7605bad7976a9abc997cb5e0abe434078 v1.2b3
065e31cf5862e27521cf5725b003aed211f091b2 v1.2b4
e72257e655454d569468da8b1189e0ec336f3536 v1.2
e63d83f8275853aaaa3d1972cb86564505e65583 v1.3b1
7d743c865a9aa6bde8b603e32e0542031bba3c33 v1.3
4fc85c82cc222554ae6b9c0b87776ed5f2b70c6e v1.4b1
129f1299d4e97e884bbbbdd00baf101d178973e6 v1.4b2
44a82ac654a4175569deed8e8a94b0cc8edee08d v1.4b3
db49494c93dc73de06d5721c74eab533a947a92c v1.4
062aed8a4ce2c91c81b80e29f02faff1cf5a761b v1.5a1
c9498ac988372575cf7028b86395b900c9b0a840 v1.5a2
dc5c968ec992aab3d40a7189df0c443d1c7a1a68 v1.5a3
746654a0af680c7d9b814b210a026eb91bec9533 v1.5a4
8ff58b5730f06be08fbbdc2bf592226f7a736201 v1.5b1
eb78658d819fb0af09a8e6f9bedcb670805ed5f6 v1.5b2
84461011a1a0ab402e352f06748f29fb5b5559e5 v1.5
44aba4d26b01fbae0403efe654f9fd0347606732 v1.5.1
fed63ccbe6dc3ac663bfe97a2f7006b1b28568f9 v1.5.2a1
21d71f2e27248a0f4e393d0fc321ecf9b89321d2 v1.5.2a2
f08c7a2a56f80741f5f192fd0ebe0b0967a203cf v1.5.2b1
8fe7ec4b4fc1518fcac89e6bf674fbbce16150a9 v1.5.2b2
39fb0dcc83dc375c1565ba65dbce0ed59b1359c9 v1.5.2c1
61c91c7f101bab3149adfcd5646ae40e048de712 v1.5.2
605eb9326ffe1fd1e43f40e2338d6652ab449fdf v1.6a1
011bee8fd9f7f4da457ec71596484fb0882c0614 v1.6a2
35c4fc1414a59888614b9be784a25f233ba67984 v2.0b1
55bba197d4870cdae62aeca00e20240a756b84f8 v2.0b2
e276329cce036a5f9e9d3451256dca5984e543dc v2.0c1
2fa4e35083e02342ca014bf5bfba46aecb816c31 v2.0
b60831eeab5a06dd3c5e8297a99e39297aa8794b v2.1a1
b382f1f07ec6b2c95551658b30c6139eeb32077a v2.1a2
d0c830db5e68edd4aaa3401216e610c9ff145826 v2.1b1
b59a536ae1ef3774fd85c17f623e8926b7b6c095 v2.1b2
d611276e9ad53b5d32d1e8065e1d811c32f7d96f v2.1c1
ff065e674af6c9ab895bd9eff7d9e9039a376c7d v2.1c2
020e95d8180d7943fe54701e1db0a7d7d87e2b1e v2.1
08796a137f1ada2462f7a3177306df5f67a767e1 v2.2a3
d054c29647f90bccb8345bd779bca1eecf2dd7f2 v2.3c1
fce5c9e9abc722394cb2e909b7e2a39080d4448e v2.3c2
92ca658fd420095b6284c9ce6e9082a80285ec9c v2.4a1
055fc6955f3c6522bfeb7ed4c671c97d5baaaac2 v2.4a2
186b72550e53533ef6175f6411f932c1298193d7 v2.4a3
53cff04283855adf88ed0c0fd3698827ca843637 v2.4b1
7e387a9dcc79954a77695adef8b593da35be1214 v2.4b2
ff80d8bbef6e13426c8a85d7f9d837b8f8f89834 v2.4c1
f31e18d313c7a4fc66914b2d27e130a0f72c0b69 v2.4
cd3f783cd08a16781e236c0b9cb5717d1d995fa9 v3.0a1
65e82140e281bf26f2e22eda05a7f9956c420f8b v3.0a2
df15827f34881b9af0936350813ced5c123c8230 v3.0a3
15f773f7300e372c56a21d59fe49ca26955a6477 v3.0a4
e35935475153377d6727d64e6c52f72c3b84015b v3.0a5
a335c4d643b1cfe14197a9ef195c9b2804f608fc v3.0b1
16ec4bb14a68ea428acf09ebf0c92981da2646f3 v3.0b2
509e30a7968e01be329ec121540b3e755fc4e566 v3.0b3
507ede9c7f7f475dfafbd4a52c22d767d10a2bc0 v3.0rc1
8fae465a39627b590385462e6095eb63af45240a v3.0rc2
e83a60c69d53f5551a306e77a6d38e9b11485496 v3.0rc3
bc1ce368986e45b1faf96f93995df46bcd75e7b8 v3.1a1
ee430e5075db2adf8124e6b94916a89ca41d3171 v3.1a2
b63020797f9678adaf4d2c3e26574a9eef2ef028 v3.1b1
4353fd0843cb31b356adc50f93d220e2e7255ef2 v3.1rc1
0b87e438e1b53e3f812cad963a7fdb65d198ba2f v3.1rc2
a69a031ac1402dede8b1ef80096436bca6d371f3 v3.1
35efb1054ec6ceca72017a587263cb6a9257340b v3.1.1rc1
8b9c0f573ab29c41c6c5fdcca82a1fe0ff5355af v3.1.1
149b8b87514d10416b598884db5f74651f625b38 v3.1.2rc1
960efa327c5d9c18df995437b0ac550cb89c9f85 v3.1.2
d18e9d71f369d8211f6ac87252c6d3211f9bd09f v3.1.3rc1
a4f75773c0060cee38b0bb651a7aba6f56b0e996 v3.1.3
32fcb9e94985cb19ce37ba9543f091c0dbe9d7dd v3.1.4rc1
c918ec9f3a76d6afedfbb5d455004de880443a3d v3.1.4
ee26aca3219cf4bb0b93352e83edcc9cb28c7802 v3.1.5rc1
75db2bc69fc9a3e4801e94e3e19801cb096208d8 v3.1.5rc2
7395330e495ec3316862ca1f6ce0aaf7bdf6785b v3.1.5
b37b7834757492d009b99cf0ca4d42d2153d7fac v3.2a1
56d4373cecb73c8b45126ba7b045b3c7b3f94b0b v3.2a2
da012d9a2c23d144e399d2e01a55b8a83ad94573 v3.2a3
d92a5b850f5e56808bedc01723906ed64c5e6e2e v3.2a4
b635cea94195780c8716e236479af319bcc26253 v3.2b1
e3af5f3a7904c0d5343ec9633ea66e7acfd23a66 v3.2b2
865d5b24bf28ca41b536befc326407c03e74a4d5 v3.2rc1
acf3e24dd0d0dfd1e20c907d696d3da965a8f56f v3.2rc2
18c1f52896501c7ee13b038454a39acb45a87979 v3.2rc3
a222a015e28d8ae9af3899258dc6c15c3d40add0 v3.2
8ffac2337a3323323d02153ac919fd1483176652 v3.2.1b1
cfa9364997c7f2e67b9cbb45c3a5fa3bba4e4999 v3.2.1rc1
5df549718fb4841ff521fe051f6b54f290fad5d8 v3.2.1rc2
ac1f7e5c05104d557d5acd922e95625ba5d1fe10 v3.2.1
c860feaa348d663e598986894ee4680480577e15 v3.2.2rc1
137e45f15c0bd262c9ad4c032d97425bc0589456 v3.2.2
7085403daf439adb3f9e70ef13f6bedb1c447376 v3.2.3rc1
428f05cb7277e1d42bb9dd8d1af6b6270ebc6112 v3.2.3rc2
3d0686d90f55a78f96d9403da2c52dc2411419d0 v3.2.3
b2cb7bc1edb8493c0a78f9331eae3e8fba6a881d v3.2.4rc1
1e10bdeabe3de02f038a63c001911561ac1d13a7 v3.2.4
cef745775b6583446572cffad704100983db2bea v3.2.5
f1a9a6505731714f0e157453ff850e3b71615c45 v3.3.0a1
2f69db52d6de306cdaef0a0cc00cc823fb350b01 v3.3.0a2
0b53b70a40a00013505eb35e3660057b62be77be v3.3.0a3
7c51388a3aa7ce76a8541bbbdfc05d2d259a162c v3.3.0a4
e15c554cd43eb23bc0a528a4e8741da9bbec9607 v3.3.0b1
4972a8f1b2aa3d7cdd64dc96aa7fa112fe1ea343 v3.3.0b2
8bb5c7bc46ba43804480f3e328e1fa956672c885 v3.3.0rc1
88a0792e8ba3e4916b24c7e7a522c277d326d66e v3.3.0rc2
c191d21cefafb3832c45570e84854e309aa62eaa v3.3.0rc3
bd8afb90ebf28ba4edc901d4a235f75e7bbc79fd v3.3.0
92c2cfb924055ce68c4f78f836dcfe688437ceb8 v3.3.1rc1
d9893d13c6289aa03d33559ec67f97dcbf5c9e3c v3.3.1
d047928ae3f6314a13b6137051315453d0ae89b6 v3.3.2
fd53c500f8b80f54f3ecedec9da2e8c7e52a6888 v3.3.3rc1
d32442c0e60dfbd71234e807d3d1dedd227495a9 v3.3.3rc2
c3896275c0f61b2510a6c7e6c458a750359a91b8 v3.3.3
fa92f5f940c6c0d839d7f0611e4b717606504a3c v3.3.4rc1
7ff62415e4263c432c8acf6e424224209211eadb v3.3.4
46535f65e7f3bcdcf176f36d34bc1fed719ffd2b v3.4.0a1
9265a2168e2cb2a84785d8717792acc661e6b692 v3.4.0a2
dd9cdf90a5073510877e9dd5112f8e6cf20d5e89 v3.4.0a3
e245b0d7209bb6d0e19316e1e2af1aa9c2139104 v3.4.0a4
3405dc9a6afaa0a06dd1f6f182ec5c998dce6f5f v3.4.0b1
ba32913eb13ec545a46dd0ce18035b6c416f0d78 v3.4.0b2
a97ce3ecc96af79bd2e1ac66ce48d9138e0ca749 v3.4.0b3
5e088cea8660677969113741c1313d570d977e02 v3.4.0rc1
a300712ed38c9a242b736c44e806caea25a6dc05 v3.4.0rc2
.hgtouch
+15
View File
@@ -0,0 +1,15 @@
# -*- Makefile -*-
# Define dependencies of generated files that are checked into hg.
# The syntax of this file uses make rule dependencies, without actions
Python/importlib.h: Lib/importlib/_bootstrap.py Modules/_freeze_importlib.c
Include/Python-ast.h: Parser/Python.asdl Parser/asdl.py Parser/asdl_c.py
Python/Python-ast.c: Include/Python-ast.h
Python/opcode_targets.h: Python/makeopcodetargets.py Lib/opcode.py
Objects/typeslots.inc: Include/typeslots.h Objects/typeslots.py
Include/graminit.h: Grammar/Grammar Parser/acceler.c Parser/grammar1.c Parser/listnode.c Parser/node.c Parser/parser.c Parser/bitset.c Parser/metagrammar.c Parser/firstsets.c Parser/grammar.c Parser/pgen.c Objects/obmalloc.c Python/dynamic_annotations.c Python/mysnprintf.c Python/pyctype.c Parser/tokenizer_pgen.c Parser/printgrammar.c Parser/parsetok_pgen.c Parser/pgenmain.c
Python/graminit.c: Include/graminit.h Grammar/Grammar Parser/acceler.c Parser/grammar1.c Parser/listnode.c Parser/node.c Parser/parser.c Parser/bitset.c Parser/metagrammar.c Parser/firstsets.c Parser/grammar.c Parser/pgen.c Objects/obmalloc.c Python/dynamic_annotations.c Python/mysnprintf.c Python/pyctype.c Parser/tokenizer_pgen.c Parser/printgrammar.c Parser/parsetok_pgen.c Parser/pgenmain.c
23524_hack_2.patch
+433
View File
@@ -0,0 +1,433 @@
# HG changeset patch
# User Steve Dower <steve.dower@microsoft.com>
# Date 1424930096 28800
# Wed Feb 25 21:54:56 2015 -0800
# Node ID 2341dc356f166c02b3140a9244c49ca03177a00c
# Parent cabd257b1070b056928061cac80b598eebbeb979
Issue #23524: Replace _PyVerify_fd function with calling _set_thread_local_invalid_parameter_handler on every thread.
diff --git a/Include/fileobject.h b/Include/fileobject.h
--- a/Include/fileobject.h
+++ b/Include/fileobject.h
@@ -32,17 +32,6 @@
#ifndef Py_LIMITED_API
PyAPI_FUNC(PyObject *) PyFile_NewStdPrinter(int);
PyAPI_DATA(PyTypeObject) PyStdPrinter_Type;
-
-#if defined _MSC_VER && _MSC_VER >= 1400
-/* A routine to check if a file descriptor is valid on Windows. Returns 0
- * and sets errno to EBADF if it isn't. This is to avoid Assertions
- * from various functions in the Windows CRT beginning with
- * Visual Studio 2005
- */
-int _PyVerify_fd(int fd);
-#else
-#define _PyVerify_fd(A) (1) /* dummy */
-#endif
#endif /* Py_LIMITED_API */
/* A routine to check if a file descriptor can be select()-ed. */
diff --git a/Include/fileutils.h b/Include/fileutils.h
--- a/Include/fileutils.h
+++ b/Include/fileutils.h
@@ -108,6 +108,18 @@
PyAPI_FUNC(int) _Py_set_blocking(int fd, int blocking);
#endif /* !MS_WINDOWS */
+#if defined _MSC_VER && _MSC_VER >= 1400
+/* A routine to check if a file descriptor is valid on Windows. Returns 0
+ * and sets errno to EBADF if it isn't. This is to avoid Assertions
+ * from various functions in the Windows CRT beginning with
+ * Visual Studio 2005
+ */
+int _PyVerify_fd(int fd);
+
+#else
+#define _PyVerify_fd(A) (1) /* dummy */
+#endif
+
#endif /* Py_LIMITED_API */
#ifdef __cplusplus
diff --git a/Modules/_io/fileio.c b/Modules/_io/fileio.c
--- a/Modules/_io/fileio.c
+++ b/Modules/_io/fileio.c
@@ -182,7 +182,7 @@
{
#if defined(HAVE_FSTAT) || defined(MS_WINDOWS)
struct _Py_stat_struct buf;
- if (!_PyVerify_fd(fd) || (_Py_fstat(fd, &buf) < 0 && errno == EBADF)) {
+ if (_Py_fstat(fd, &buf) < 0 && errno == EBADF) {
PyObject *exc;
char *msg = strerror(EBADF);
exc = PyObject_CallFunction(PyExc_OSError, "(is)",
diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c
--- a/Modules/posixmodule.c
+++ b/Modules/posixmodule.c
@@ -1051,99 +1051,16 @@
}
-#if defined _MSC_VER && _MSC_VER >= 1400
-/* Microsoft CRT in VS2005 and higher will verify that a filehandle is
- * valid and raise an assertion if it isn't.
- * Normally, an invalid fd is likely to be a C program error and therefore
- * an assertion can be useful, but it does contradict the POSIX standard
- * which for write(2) states:
- * "Otherwise, -1 shall be returned and errno set to indicate the error."
- * "[EBADF] The fildes argument is not a valid file descriptor open for
- * writing."
- * Furthermore, python allows the user to enter any old integer
- * as a fd and should merely raise a python exception on error.
- * The Microsoft CRT doesn't provide an official way to check for the
- * validity of a file descriptor, but we can emulate its internal behaviour
- * by using the exported __pinfo data member and knowledge of the
- * internal structures involved.
- * The structures below must be updated for each version of visual studio
- * according to the file internal.h in the CRT source, until MS comes
- * up with a less hacky way to do this.
- * (all of this is to avoid globally modifying the CRT behaviour using
- * _set_invalid_parameter_handler() and _CrtSetReportMode())
+#if defined _MSC_VER && _MSC_VER >= 1400 && _MSC_VER < 1900
+/* Legacy implementation of _PyVerify_fd_dup2 while transitioning to
+ * MSVC 14.0. This should eventually be removed. (issue23524)
*/
-/* The actual size of the structure is determined at runtime.
- * Only the first items must be present.
- */
-
-#if _MSC_VER >= 1900
-
-typedef struct {
- CRITICAL_SECTION lock;
- intptr_t osfhnd;
- __int64 startpos;
- char osfile;
-} my_ioinfo;
-
-#define IOINFO_L2E 6
-#define IOINFO_ARRAYS 128
-
-#else
-
-typedef struct {
- intptr_t osfhnd;
- char osfile;
-} my_ioinfo;
-
#define IOINFO_L2E 5
#define IOINFO_ARRAYS 64
-
-#endif
-
-extern __declspec(dllimport) char * __pioinfo[];
#define IOINFO_ARRAY_ELTS (1 << IOINFO_L2E)
#define _NHANDLE_ (IOINFO_ARRAYS * IOINFO_ARRAY_ELTS)
-#define FOPEN 0x01
#define _NO_CONSOLE_FILENO (intptr_t)-2
-/* This function emulates what the windows CRT does to validate file handles */
-int
-_PyVerify_fd(int fd)
-{
- const int i1 = fd >> IOINFO_L2E;
- const int i2 = fd & ((1 << IOINFO_L2E) - 1);
-
- static size_t sizeof_ioinfo = 0;
-
- /* Determine the actual size of the ioinfo structure,
- * as used by the CRT loaded in memory
- */
- if (sizeof_ioinfo == 0 && __pioinfo[0] != NULL) {
- sizeof_ioinfo = _msize(__pioinfo[0]) / IOINFO_ARRAY_ELTS;
- }
- if (sizeof_ioinfo == 0) {
- /* This should not happen... */
- goto fail;
- }
-
- /* See that it isn't a special CLEAR fileno */
- if (fd != _NO_CONSOLE_FILENO) {
- /* Microsoft CRT would check that 0<=fd<_nhandle but we can't do that. Instead
- * we check pointer validity and other info
- */
- if (0 <= i1 && i1 < IOINFO_ARRAYS && __pioinfo[i1] != NULL) {
- /* finally, check that the file is open */
- my_ioinfo* info = (my_ioinfo*)(__pioinfo[i1] + i2 * sizeof_ioinfo);
- if (info->osfile & FOPEN) {
- return 1;
- }
- }
- }
- fail:
- errno = EBADF;
- return 0;
-}
-
/* the special case of checking dup2. The target fd must be in a sensible range */
static int
_PyVerify_fd_dup2(int fd1, int fd2)
@@ -1158,8 +1075,7 @@
return 0;
}
#else
-/* dummy version. _PyVerify_fd() is already defined in fileobject.h */
-#define _PyVerify_fd_dup2(A, B) (1)
+#define _PyVerify_fd_dup2(fd1, fd2) (_PyVerify_fd(fd1) && (fd2) >= 0)
#endif
#ifdef MS_WINDOWS
diff --git a/PC/invalid_parameter_handler.c b/PC/invalid_parameter_handler.c
new file mode 100644
--- /dev/null
+++ b/PC/invalid_parameter_handler.c
@@ -0,0 +1,22 @@
+#ifdef _MSC_VER
+
+#include <stdlib.h>
+
+#if _MSC_VER >= 1900
+/* pyconfig.h uses this function in the _Py_BEGIN/END_SUPPRESS_IPH
+ * macros. It does not need to be defined when building using MSVC
+ * earlier than 14.0 (_MSC_VER == 1900).
+ */
+
+static void __cdecl _silent_invalid_parameter_handler(
+ wchar_t const* expression,
+ wchar_t const* function,
+ wchar_t const* file,
+ unsigned int line,
+ uintptr_t pReserved) { }
+
+void *_Py_silent_invalid_parameter_handler =
+ (void*)_silent_invalid_parameter_handler;
+#endif
+
+#endif
diff --git a/PCbuild/pythoncore.vcxproj b/PCbuild/pythoncore.vcxproj
--- a/PCbuild/pythoncore.vcxproj
+++ b/PCbuild/pythoncore.vcxproj
@@ -333,6 +333,7 @@
<ClCompile Include="..\Parser\parser.c" />
<ClCompile Include="..\Parser\parsetok.c" />
<ClCompile Include="..\Parser\tokenizer.c" />
+ <ClCompile Include="..\PC\invalid_parameter_handler.c" />
<ClCompile Include="..\PC\winreg.c" />
<ClCompile Include="..\PC\config.c" />
<ClCompile Include="..\PC\getpathp.c" />
@@ -394,25 +395,21 @@
<Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
<ImportGroup Label="ExtensionTargets">
</ImportGroup>
-
<Target Name="_GetBuildInfo" BeforeTargets="PrepareForBuild">
- <Exec Command='hg id -b &gt; "$(IntDir)hgbranch.txt"' ContinueOnError="true" />
- <Exec Command='hg id -i &gt; "$(IntDir)hgversion.txt"' ContinueOnError="true" />
- <Exec Command='hg id -t &gt; "$(IntDir)hgtag.txt"' ContinueOnError="true" />
-
+ <Exec Command="hg id -b &gt; &quot;$(IntDir)hgbranch.txt&quot;" ContinueOnError="true" />
+ <Exec Command="hg id -i &gt; &quot;$(IntDir)hgversion.txt&quot;" ContinueOnError="true" />
+ <Exec Command="hg id -t &gt; &quot;$(IntDir)hgtag.txt&quot;" ContinueOnError="true" />
<PropertyGroup>
<HgBranch Condition="Exists('$(IntDir)hgbranch.txt')">$([System.IO.File]::ReadAllText('$(IntDir)hgbranch.txt').Trim())</HgBranch>
<HgVersion Condition="Exists('$(IntDir)hgversion.txt')">$([System.IO.File]::ReadAllText('$(IntDir)hgversion.txt').Trim())</HgVersion>
<HgTag Condition="Exists('$(IntDir)hgtag.txt')">$([System.IO.File]::ReadAllText('$(IntDir)hgtag.txt').Trim())</HgTag>
</PropertyGroup>
-
<ItemGroup>
<ClCompile Include="..\Modules\getbuildinfo.c">
<PreprocessorDefinitions>HGVERSION="$(HgVersion)";HGTAG="$(HgTag)";HGBRANCH="$(HgBranch)";%(PreprocessorDefinitions)</PreprocessorDefinitions>
</ClCompile>
</ItemGroup>
</Target>
-
<Target Name="_WarnAboutToolset" BeforeTargets="PrepareForBuild" Condition="$(PlatformToolset) != 'v140'">
<Warning Text="Toolset $(PlatformToolset) is not used for official builds. Your build may have errors or incompatibilities." />
</Target>
diff --git a/PCbuild/pythoncore.vcxproj.filters b/PCbuild/pythoncore.vcxproj.filters
--- a/PCbuild/pythoncore.vcxproj.filters
+++ b/PCbuild/pythoncore.vcxproj.filters
@@ -959,6 +959,9 @@
<ClCompile Include="..\Modules\hashtable.c">
<Filter>Modules</Filter>
</ClCompile>
+ <ClCompile Include="..\PC\invalid_parameter_handler.c">
+ <Filter>PC</Filter>
+ </ClCompile>
</ItemGroup>
<ItemGroup>
<ResourceCompile Include="..\PC\python_nt.rc">
diff --git a/Python/fileutils.c b/Python/fileutils.c
--- a/Python/fileutils.c
+++ b/Python/fileutils.c
@@ -3,6 +3,7 @@
#include <locale.h>
#ifdef MS_WINDOWS
+# include <malloc.h>
# include <windows.h>
#endif
@@ -636,14 +637,10 @@
else
h = (HANDLE)_get_osfhandle(fd);
- /* Protocol violation: we explicitly clear errno, instead of
- setting it to a POSIX error. Callers should use GetLastError. */
errno = 0;
if (h == INVALID_HANDLE_VALUE) {
- /* This is really a C library error (invalid file handle).
- We set the Win32 error to the closes one matching. */
- SetLastError(ERROR_INVALID_HANDLE);
+ errno = EBADF;
return -1;
}
memset(result, 0, sizeof(*result));
@@ -652,6 +649,7 @@
if (type == FILE_TYPE_UNKNOWN) {
DWORD error = GetLastError();
if (error != 0) {
+ errno = EINVAL;
return -1;
}
/* else: valid but unknown file */
@@ -666,6 +664,7 @@
}
if (!GetFileInformationByHandle(h, &info)) {
+ errno = EINVAL;
return -1;
}
@@ -1267,3 +1266,102 @@
}
#endif
+#ifdef _MSC_VER
+#if _MSC_VER >= 1900
+
+/* This function lets the Windows CRT validate the file handle without
+ terminating the process if it's invalid. */
+int
+_PyVerify_fd(int fd)
+{
+ intptr_t osh;
+ /* Fast check for the only condition we know */
+ if (fd < 0) {
+ _set_errno(EBADF);
+ return 0;
+ }
+ osh = _get_osfhandle(fd);
+ return osh != (intptr_t)-1;
+}
+
+#elif _MSC_VER >= 1400
+/* Legacy implementation of _PyVerify_fd while transitioning to
+ * MSVC 14.0. This should eventually be removed. (issue23524)
+ */
+
+/* Microsoft CRT in VS2005 and higher will verify that a filehandle is
+ * valid and raise an assertion if it isn't.
+ * Normally, an invalid fd is likely to be a C program error and therefore
+ * an assertion can be useful, but it does contradict the POSIX standard
+ * which for write(2) states:
+ * "Otherwise, -1 shall be returned and errno set to indicate the error."
+ * "[EBADF] The fildes argument is not a valid file descriptor open for
+ * writing."
+ * Furthermore, python allows the user to enter any old integer
+ * as a fd and should merely raise a python exception on error.
+ * The Microsoft CRT doesn't provide an official way to check for the
+ * validity of a file descriptor, but we can emulate its internal behaviour
+ * by using the exported __pinfo data member and knowledge of the
+ * internal structures involved.
+ * The structures below must be updated for each version of visual studio
+ * according to the file internal.h in the CRT source, until MS comes
+ * up with a less hacky way to do this.
+ * (all of this is to avoid globally modifying the CRT behaviour using
+ * _set_invalid_parameter_handler() and _CrtSetReportMode())
+ */
+/* The actual size of the structure is determined at runtime.
+ * Only the first items must be present.
+ */
+typedef struct {
+ intptr_t osfhnd;
+ char osfile;
+} my_ioinfo;
+
+extern __declspec(dllimport) char * __pioinfo[];
+#define IOINFO_L2E 5
+#define IOINFO_ARRAYS 64
+#define IOINFO_ARRAY_ELTS (1 << IOINFO_L2E)
+#define _NHANDLE_ (IOINFO_ARRAYS * IOINFO_ARRAY_ELTS)
+#define FOPEN 0x01
+#define _NO_CONSOLE_FILENO (intptr_t)-2
+
+/* This function emulates what the windows CRT does to validate file handles */
+int
+_PyVerify_fd(int fd)
+{
+ const int i1 = fd >> IOINFO_L2E;
+ const int i2 = fd & ((1 << IOINFO_L2E) - 1);
+
+ static size_t sizeof_ioinfo = 0;
+
+ /* Determine the actual size of the ioinfo structure,
+ * as used by the CRT loaded in memory
+ */
+ if (sizeof_ioinfo == 0 && __pioinfo[0] != NULL) {
+ sizeof_ioinfo = _msize(__pioinfo[0]) / IOINFO_ARRAY_ELTS;
+ }
+ if (sizeof_ioinfo == 0) {
+ /* This should not happen... */
+ goto fail;
+ }
+
+ /* See that it isn't a special CLEAR fileno */
+ if (fd != _NO_CONSOLE_FILENO) {
+ /* Microsoft CRT would check that 0<=fd<_nhandle but we can't do that. Instead
+ * we check pointer validity and other info
+ */
+ if (0 <= i1 && i1 < IOINFO_ARRAYS && __pioinfo[i1] != NULL) {
+ /* finally, check that the file is open */
+ my_ioinfo* info = (my_ioinfo*)(__pioinfo[i1] + i2 * sizeof_ioinfo);
+ if (info->osfile & FOPEN) {
+ return 1;
+ }
+ }
+ }
+ fail:
+ errno = EBADF;
+ return 0;
+}
+
+#endif /* _MSC_VER >= 1900 || _MSC_VER >= 1400 */
+#endif /* defined _MSC_VER */
diff --git a/Python/pystate.c b/Python/pystate.c
--- a/Python/pystate.c
+++ b/Python/pystate.c
@@ -22,6 +22,12 @@
#endif
#endif
+#if defined _MSC_VER && _MSC_VER >= 1900
+/* Issue #23524: Temporary fix to disable termination due to invalid parameters */
+PyAPI_DATA(void*) _Py_silent_invalid_parameter_handler;
+#include <stdlib.h>
+#endif
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -222,6 +228,11 @@
tstate->next->prev = tstate;
interp->tstate_head = tstate;
HEAD_UNLOCK();
+
+#if defined _MSC_VER && _MSC_VER >= 1900
+ /* Issue #23524: Temporary fix to disable termination due to invalid parameters */
+ _set_thread_local_invalid_parameter_handler((_invalid_parameter_handler)_Py_silent_invalid_parameter_handler);
+#endif
}
return tstate;
Doc/README.txt
+153
View File
@@ -0,0 +1,153 @@
Python Documentation README
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This directory contains the reStructuredText (reST) sources to the Python
documentation. You don't need to build them yourself, prebuilt versions are
available at http://docs.python.org/download/.
Documentation on the authoring Python documentation, including information about
both style and markup, is available in the "Documenting Python" chapter of the
developers guide (http://docs.python.org/devguide/documenting.html).
There's also a chapter intended to point out differences to
those familiar with the previous docs written in LaTeX.
Building the docs
=================
You need to have Python 2.4 or higher installed; the toolset used to build the
docs is written in Python. It is called *Sphinx*, it is not included in this
tree, but maintained separately. Also needed are the docutils, supplying the
base markup that Sphinx uses, Jinja, a templating engine, and optionally
Pygments, a code highlighter.
Using make
----------
Luckily, a Makefile has been prepared so that on Unix, provided you have
installed Python and Subversion, you can just run ::
make html
to check out the necessary toolset in the `tools/` subdirectory and build the
HTML output files. To view the generated HTML, point your favorite browser at
the top-level index `build/html/index.html` after running "make".
To use a Python interpreter that's not called ``python``, use the standard
way to set Makefile variables, using e.g. ::
make html PYTHON=/usr/bin/python2.5
Available make targets are:
* "html", which builds standalone HTML files for offline viewing.
* "htmlhelp", which builds HTML files and a HTML Help project file usable to
convert them into a single Compiled HTML (.chm) file -- these are popular
under Microsoft Windows, but very handy on every platform.
To create the CHM file, you need to run the Microsoft HTML Help Workshop over
the generated project (.hhp) file.
* "latex", which builds LaTeX source files as input to "pdflatex" to produce
PDF documents.
* "text", which builds a plain text file for each source file.
* "epub", which builds an EPUB document, suitable to be viewed on e-book
readers.
* "linkcheck", which checks all external references to see whether they are
broken, redirected or malformed, and outputs this information to stdout as
well as a plain-text (.txt) file.
* "changes", which builds an overview over all versionadded/versionchanged/
deprecated items in the current version. This is meant as a help for the
writer of the "What's New" document.
* "coverage", which builds a coverage overview for standard library modules and
C API.
* "pydoc-topics", which builds a Python module containing a dictionary with
plain text documentation for the labels defined in
`tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
keyword help.
A "make update" updates the Subversion checkouts in `tools/`.
Without make
------------
You'll need to install the Sphinx package, either by checking it out via ::
svn co http://svn.python.org/projects/external/Sphinx-1.0.7/sphinx tools/sphinx
or by installing it from PyPI.
Then, you need to install Docutils, either by checking it out via ::
svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils
or by installing it from http://docutils.sf.net/.
You also need Jinja2, either by checking it out via ::
svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2
or by installing it from PyPI.
You can optionally also install Pygments, either as a checkout via ::
svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments
or from PyPI at http://pypi.python.org/pypi/Pygments.
Then, make an output directory, e.g. under `build/`, and run ::
python tools/sphinx-build.py -b<builder> . build/<outputdirectory>
where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
the make targets above).
Contributing
============
Bugs in the content should be reported to the Python bug tracker at
http://bugs.python.org.
Bugs in the toolset should be reported in the Sphinx bug tracker at
http://www.bitbucket.org/birkenfeld/sphinx/issues/.
You can also send a mail to the Python Documentation Team at docs@python.org,
and we will process your request as soon as possible.
If you want to help the Documentation Team, you are always welcome. Just send
a mail to docs@python.org.
Copyright notice
================
The Python source is copyrighted, but you can freely use and copy it
as long as you don't change or remove the copyright notice:
----------------------------------------------------------------------
Copyright (c) 2000-2014 Python Software Foundation.
All rights reserved.
Copyright (c) 2000 BeOpen.com.
All rights reserved.
Copyright (c) 1995-2000 Corporation for National Research Initiatives.
All rights reserved.
Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
All rights reserved.
See the file "license.rst" for information on usage and redistribution
of this file, and for a DISCLAIMER OF ALL WARRANTIES.
----------------------------------------------------------------------
Doc/about.rst
+39
View File
@@ -0,0 +1,39 @@
=====================
About these documents
=====================
These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
document processor specifically written for the Python documentation.
.. _reStructuredText: http://docutils.sf.net/rst.html
.. _Sphinx: http://sphinx-doc.org/
.. In the online version of these documents, you can submit comments and suggest
changes directly on the documentation pages.
Development of the documentation and its toolchain is an entirely volunteer
effort, just like Python itself. If you want to contribute, please take a
look at the :ref:`reporting-bugs` page for information on how to do so. New
volunteers are always welcome!
Many thanks go to:
* Fred L. Drake, Jr., the creator of the original Python documentation toolset
and writer of much of the content;
* the `Docutils <http://docutils.sf.net/>`_ project for creating
reStructuredText and the Docutils suite;
* Fredrik Lundh for his `Alternative Python Reference
<http://effbot.org/zone/pyref.htm>`_ project from which Sphinx got many good
ideas.
Contributors to the Python Documentation
----------------------------------------
Many people have contributed to the Python language, the Python standard
library, and the Python documentation. See :source:`Misc/ACKS` in the Python
source distribution for a partial list of contributors.
It is only with the input and contributions of the Python community
that Python has such wonderful documentation -- Thank You!
Doc/bugs.rst
+87
View File
@@ -0,0 +1,87 @@
.. _reporting-bugs:
**************
Reporting Bugs
**************
Python is a mature programming language which has established a reputation for
stability. In order to maintain this reputation, the developers would like to
know of any deficiencies you find in Python.
Documentation bugs
==================
If you find a bug in this documentation or would like to propose an improvement,
please submit a bug report on the :ref:`tracker <using-the-tracker>`. If you
have a suggestion how to fix it, include that as well.
If you're short on time, you can also email your bug report to docs@python.org.
'docs@' is a mailing list run by volunteers; your request will be noticed,
though it may take a while to be processed.
.. seealso::
`Documentation bugs`_ on the Python issue tracker
.. _using-the-tracker:
Using the Python issue tracker
==============================
Bug reports for Python itself should be submitted via the Python Bug Tracker
(http://bugs.python.org/). The bug tracker offers a Web form which allows
pertinent information to be entered and submitted to the developers.
The first step in filing a report is to determine whether the problem has
already been reported. The advantage in doing so, aside from saving the
developers time, is that you learn what has been done to fix it; it may be that
the problem has already been fixed for the next release, or additional
information is needed (in which case you are welcome to provide it if you can!).
To do this, search the bug database using the search box on the top of the page.
If the problem you're reporting is not already in the bug tracker, go back to
the Python Bug Tracker and log in. If you don't already have a tracker account,
select the "Register" link or, if you use OpenID, one of the OpenID provider
logos in the sidebar. It is not possible to submit a bug report anonymously.
Being now logged in, you can submit a bug. Select the "Create New" link in the
sidebar to open the bug reporting form.
The submission form has a number of fields. For the "Title" field, enter a
*very* short description of the problem; less than ten words is good. In the
"Type" field, select the type of your problem; also select the "Component" and
"Versions" to which the bug relates.
In the "Comment" field, describe the problem in detail, including what you
expected to happen and what did happen. Be sure to include whether any
extension modules were involved, and what hardware and software platform you
were using (including version information as appropriate).
Each bug report will be assigned to a developer who will determine what needs to
be done to correct the problem. You will receive an update each time action is
taken on the bug.
.. seealso::
`How to Report Bugs Effectively <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
Article which goes into some detail about how to create a useful bug report.
This describes what kind of information is useful and why it is useful.
`Bug Writing Guidelines <http://developer.mozilla.org/en/docs/Bug_writing_guidelines>`_
Information about writing a good bug report. Some of this is specific to the
Mozilla project, but describes general good practices.
Getting started contributing to Python yourself
===============================================
Beyond just reporting bugs that you find, you are also welcome to submit
patches to fix them. You can find more information on how to get started
patching Python in the `Python Developer's Guide`_. If you have questions,
the `core-mentorship mailing list`_ is a friendly place to get answers to
any and all questions pertaining to the process of fixing issues in Python.
.. _Documentation bugs: http://bugs.python.org/issue?@filter=status&@filter=components&components=4&status=1&@columns=id,activity,title,status&@sort=-activity
.. _Python Developer's Guide: http://docs.python.org/devguide/
.. _core-mentorship mailing list: https://mail.python.org/mailman/listinfo/core-mentorship/
Doc/c-api/abstract.rst
+26
View File
@@ -0,0 +1,26 @@
.. highlightlang:: c
.. _abstract:
**********************
Abstract Objects Layer
**********************
The functions in this chapter interact with Python objects regardless of their
type, or with wide classes of object types (e.g. all numerical types, or all
sequence types). When used on object types for which they do not apply, they
will raise a Python exception.
It is not possible to use these functions on objects that are not properly
initialized, such as a list object that has been created by :c:func:`PyList_New`,
but whose items have not been set to some non-\ ``NULL`` value yet.
.. toctree::
object.rst
number.rst
sequence.rst
mapping.rst
iter.rst
buffer.rst
objbuffer.rst
Doc/c-api/allocation.rst
+71
View File
@@ -0,0 +1,71 @@
.. highlightlang:: c
.. _allocating-objects:
Allocating Objects on the Heap
==============================
.. c:function:: PyObject* _PyObject_New(PyTypeObject *type)
.. c:function:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
.. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
Initialize a newly-allocated object *op* with its type and initial
reference. Returns the initialized object. If *type* indicates that the
object participates in the cyclic garbage detector, it is added to the
detector's set of observed objects. Other fields of the object are not
affected.
.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
This does everything :c:func:`PyObject_Init` does, and also initializes the
length information for a variable-size object.
.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
are not initialized; the object's reference count will be one. The size of
the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of
the type object.
.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
are not initialized. The allocated memory allows for the *TYPE* structure
plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of
*type*. This is useful for implementing objects like tuples, which are
able to determine their size at construction time. Embedding the array of
fields into the same allocation decreases the number of allocations,
improving the memory management efficiency.
.. c:function:: void PyObject_Del(PyObject *op)
Releases memory allocated to an object using :c:func:`PyObject_New` or
:c:func:`PyObject_NewVar`. This is normally called from the
:c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type. The fields of
the object should not be accessed after this call as the memory is no
longer a valid Python object.
.. c:var:: PyObject _Py_NoneStruct
Object which is visible in Python as ``None``. This should only be accessed
using the :c:macro:`Py_None` macro, which evaluates to a pointer to this
object.
.. seealso::
:c:func:`PyModule_Create`
To allocate and create extension modules.
Doc/c-api/apiabiversion.rst
+39
View File
@@ -0,0 +1,39 @@
.. highlightlang:: c
.. _apiabiversion:
***********************
API and ABI Versioning
***********************
``PY_VERSION_HEX`` is the Python version number encoded in a single integer.
For example if the ``PY_VERSION_HEX`` is set to ``0x030401a2``, the underlying
version information can be found by treating it as a 32 bit number in
the following manner:
+-------+-------------------------+------------------------------------------------+
| Bytes | Bits (big endian order) | Meaning |
+=======+=========================+================================================+
| ``1`` | ``1-8`` | ``PY_MAJOR_VERSION`` (the ``3`` in |
| | | ``3.4.1a2``) |
+-------+-------------------------+------------------------------------------------+
| ``2`` | ``9-16`` | ``PY_MINOR_VERSION`` (the ``4`` in |
| | | ``3.4.1a2``) |
+-------+-------------------------+------------------------------------------------+
| ``3`` | ``17-24`` | ``PY_MICRO_VERSION`` (the ``1`` in |
| | | ``3.4.1a2``) |
+-------+-------------------------+------------------------------------------------+
| ``4`` | ``25-28`` | ``PY_RELEASE_LEVEL`` (``0xA`` for alpha, |
| | | ``0xB`` for beta, ``0xC`` for release |
| | | candidate and ``0xF`` for final), in this |
| | | case it is alpha. |
+-------+-------------------------+------------------------------------------------+
| | ``29-32`` | ``PY_RELEASE_SERIAL`` (the ``2`` in |
| | | ``3.4.1a2``, zero for final releases) |
+-------+-------------------------+------------------------------------------------+
Thus ``3.4.1a2`` is hexversion ``0x030401a2``.
All the given macros are defined in :source:`Include/patchlevel.h`.
Doc/c-api/arg.rst
+639
View File
File diff suppressed because it is too large Load Diff
Doc/c-api/bool.rst
+46
View File
@@ -0,0 +1,46 @@
.. highlightlang:: c
.. _boolobjects:
Boolean Objects
---------------
Booleans in Python are implemented as a subclass of integers. There are only
two booleans, :const:`Py_False` and :const:`Py_True`. As such, the normal
creation and deletion functions don't apply to booleans. The following macros
are available, however.
.. c:function:: int PyBool_Check(PyObject *o)
Return true if *o* is of type :c:data:`PyBool_Type`.
.. c:var:: PyObject* Py_False
The Python ``False`` object. This object has no methods. It needs to be
treated just like any other object with respect to reference counts.
.. c:var:: PyObject* Py_True
The Python ``True`` object. This object has no methods. It needs to be treated
just like any other object with respect to reference counts.
.. c:macro:: Py_RETURN_FALSE
Return :const:`Py_False` from a function, properly incrementing its reference
count.
.. c:macro:: Py_RETURN_TRUE
Return :const:`Py_True` from a function, properly incrementing its reference
count.
.. c:function:: PyObject* PyBool_FromLong(long v)
Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
truth value of *v*.
Doc/c-api/buffer.rst
+496
View File
@@ -0,0 +1,496 @@
.. highlightlang:: c
.. index::
single: buffer protocol
single: buffer interface; (see buffer protocol)
single: buffer object; (see buffer protocol)
.. _bufferobjects:
Buffer Protocol
---------------
.. sectionauthor:: Greg Stein <gstein@lyra.org>
.. sectionauthor:: Benjamin Peterson
.. sectionauthor:: Stefan Krah
Certain objects available in Python wrap access to an underlying memory
array or *buffer*. Such objects include the built-in :class:`bytes` and
:class:`bytearray`, and some extension types like :class:`array.array`.
Third-party libraries may define their own types for special purposes, such
as image processing or numeric analysis.
While each of these types have their own semantics, they share the common
characteristic of being backed by a possibly large memory buffer. It is
then desirable, in some situations, to access that buffer directly and
without intermediate copying.
Python provides such a facility at the C level in the form of the :ref:`buffer
protocol <bufferobjects>`. This protocol has two sides:
.. index:: single: PyBufferProcs
- on the producer side, a type can export a "buffer interface" which allows
objects of that type to expose information about their underlying buffer.
This interface is described in the section :ref:`buffer-structs`;
- on the consumer side, several means are available to obtain a pointer to
the raw underlying data of an object (for example a method parameter).
Simple objects such as :class:`bytes` and :class:`bytearray` expose their
underlying buffer in byte-oriented form. Other forms are possible; for example,
the elements exposed by a :class:`array.array` can be multi-byte values.
An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
method of file objects: any object that can export a series of bytes through
the buffer interface can be written to a file. While :meth:`write` only
needs read-only access to the internal contents of the object passed to it,
other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
to the contents of their argument. The buffer interface allows objects to
selectively allow or reject exporting of read-write and read-only buffers.
There are two ways for a consumer of the buffer interface to acquire a buffer
over a target object:
* call :c:func:`PyObject_GetBuffer` with the right parameters;
* call :c:func:`PyArg_ParseTuple` (or one of its siblings) with one of the
``y*``, ``w*`` or ``s*`` :ref:`format codes <arg-parsing>`.
In both cases, :c:func:`PyBuffer_Release` must be called when the buffer
isn't needed anymore. Failure to do so could lead to various issues such as
resource leaks.
.. _buffer-structure:
Buffer structure
================
Buffer structures (or simply "buffers") are useful as a way to expose the
binary data from another object 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.
Contrary to most data types exposed by the Python interpreter, buffers
are not :c:type:`PyObject` pointers but rather simple C structures. This
allows them to be created and copied very simply. When a generic wrapper
around a buffer is needed, a :ref:`memoryview <memoryview-objects>` object
can be created.
For short instructions how to write an exporting object, see
:ref:`Buffer Object Structures <buffer-structs>`. For obtaining
a buffer, see :c:func:`PyObject_GetBuffer`.
.. c:type:: Py_buffer
.. c:member:: void \*obj
A new reference to the exporting object. The reference is owned by
the consumer and automatically decremented and set to *NULL* by
:c:func:`PyBuffer_Release`. The field is the equivalent of the return
value of any standard C-API function.
As a special case, for *temporary* buffers that are wrapped by
:c:func:`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo`
this field is *NULL*. In general, exporting objects MUST NOT
use this scheme.
.. c:member:: void \*buf
A pointer to the start of the logical structure described by the buffer
fields. This can be any location within the underlying physical memory
block of the exporter. For example, with negative :c:member:`~Py_buffer.strides`
the value may point to the end of the memory block.
For contiguous arrays, the value points to the beginning of the memory
block.
.. c:member:: Py_ssize_t len
``product(shape) * itemsize``. For contiguous arrays, this is the length
of the underlying memory block. For non-contiguous arrays, it is the length
that the logical structure would have if it were copied to a contiguous
representation.
Accessing ``((char *)buf)[0] up to ((char *)buf)[len-1]`` is only valid
if the buffer has been obtained by a request that guarantees contiguity. In
most cases such a request will be :c:macro:`PyBUF_SIMPLE` or :c:macro:`PyBUF_WRITABLE`.
.. c:member:: int readonly
An indicator of whether the buffer is read-only. This field is controlled
by the :c:macro:`PyBUF_WRITABLE` flag.
.. c:member:: Py_ssize_t itemsize
Item size in bytes of a single element. Same as the value of :func:`struct.calcsize`
called on non-NULL :c:member:`~Py_buffer.format` values.
Important exception: If a consumer requests a buffer without the
:c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_Buffer.format` will
be set to *NULL*, but :c:member:`~Py_buffer.itemsize` still has
the value for the original format.
If :c:member:`~Py_Buffer.shape` is present, the equality
``product(shape) * itemsize == len`` still holds and the consumer
can use :c:member:`~Py_buffer.itemsize` to navigate the buffer.
If :c:member:`~Py_Buffer.shape` is *NULL* as a result of a :c:macro:`PyBUF_SIMPLE`
or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
:c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
.. c:member:: const char \*format
A *NUL* terminated string in :mod:`struct` module style syntax describing
the contents of a single item. If this is *NULL*, ``"B"`` (unsigned bytes)
is assumed.
This field is controlled by the :c:macro:`PyBUF_FORMAT` flag.
.. c:member:: int ndim
The number of dimensions the memory represents as an n-dimensional array.
If it is 0, :c:member:`~Py_Buffer.buf` points to a single item representing
a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*.
The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions
to 64. Exporters MUST respect this limit, consumers of multi-dimensional
buffers SHOULD be able to handle up to :c:macro:`PyBUF_MAX_NDIM` dimensions.
.. c:member:: Py_ssize_t \*shape
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
indicating the shape of the memory as an n-dimensional array. Note that
``shape[0] * ... * shape[ndim-1] * itemsize`` MUST be equal to
:c:member:`~Py_buffer.len`.
Shape values are restricted to ``shape[n] >= 0``. The case
``shape[n] == 0`` requires special attention. See `complex arrays`_
for further information.
The shape array is read-only for the consumer.
.. c:member:: Py_ssize_t \*strides
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
giving the number of bytes to skip to get to a new element in each
dimension.
Stride values can be any integer. For regular arrays, strides are
usually positive, but a consumer MUST be able to handle the case
``strides[n] <= 0``. See `complex arrays`_ for further information.
The strides array is read-only for the consumer.
.. c:member:: Py_ssize_t \*suboffsets
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`.
If ``suboffsets[n] >= 0``, the values stored along the nth dimension are
pointers and the suboffset value dictates how many bytes to add to each
pointer after de-referencing. A suboffset value that is negative
indicates that no de-referencing should occur (striding in a contiguous
memory block).
This type of array representation is used by the Python Imaging Library
(PIL). See `complex arrays`_ for further information how to access elements
of such an array.
The suboffsets array is read-only for the consumer.
.. c:member:: void \*internal
This is for use internally by the exporting object. For example, this
might be re-cast as an integer by the exporter and used to store flags
about whether or not the shape, strides, and suboffsets arrays must be
freed when the buffer is released. The consumer MUST NOT alter this
value.
.. _buffer-request-types:
Buffer request types
====================
Buffers are usually obtained by sending a buffer request to an exporting
object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical
structure of the memory can vary drastically, the consumer uses the *flags*
argument to specify the exact buffer type it can handle.
All :c:data:`Py_buffer` fields are unambiguously defined by the request
type.
request-independent fields
~~~~~~~~~~~~~~~~~~~~~~~~~~
The following fields are not influenced by *flags* and must always be filled in
with the correct values: :c:member:`~Py_buffer.obj`, :c:member:`~Py_buffer.buf`,
:c:member:`~Py_buffer.len`, :c:member:`~Py_buffer.itemsize`, :c:member:`~Py_buffer.ndim`.
readonly, format
~~~~~~~~~~~~~~~~
.. c:macro:: PyBUF_WRITABLE
Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter
MUST provide a writable buffer or else report failure. Otherwise, the
exporter MAY provide either a read-only or writable buffer, but the choice
MUST be consistent for all consumers.
.. c:macro:: PyBUF_FORMAT
Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST
be filled in correctly. Otherwise, this field MUST be *NULL*.
:c:macro:`PyBUF_WRITABLE` can be \|'d to any of the flags in the next section.
Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:`PyBUF_WRITABLE`
can be used as a stand-alone flag to request a simple writable buffer.
:c:macro:`PyBUF_FORMAT` can be \|'d to any of the flags except :c:macro:`PyBUF_SIMPLE`.
The latter already implies format ``B`` (unsigned bytes).
shape, strides, suboffsets
~~~~~~~~~~~~~~~~~~~~~~~~~~
The flags that control the logical structure of the memory are listed
in decreasing order of complexity. Note that each flag contains all bits
of the flags below it.
.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|
+-----------------------------+-------+---------+------------+
| Request | shape | strides | suboffsets |
+=============================+=======+=========+============+
| .. c:macro:: PyBUF_INDIRECT | yes | yes | if needed |
+-----------------------------+-------+---------+------------+
| .. c:macro:: PyBUF_STRIDES | yes | yes | NULL |
+-----------------------------+-------+---------+------------+
| .. c:macro:: PyBUF_ND | yes | NULL | NULL |
+-----------------------------+-------+---------+------------+
| .. c:macro:: PyBUF_SIMPLE | NULL | NULL | NULL |
+-----------------------------+-------+---------+------------+
contiguity requests
~~~~~~~~~~~~~~~~~~~
C or Fortran contiguity can be explicitly requested, with and without stride
information. Without stride information, the buffer must be C-contiguous.
.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|
+-----------------------------------+-------+---------+------------+--------+
| Request | shape | strides | suboffsets | contig |
+===================================+=======+=========+============+========+
| .. c:macro:: PyBUF_C_CONTIGUOUS | yes | yes | NULL | C |
+-----------------------------------+-------+---------+------------+--------+
| .. c:macro:: PyBUF_F_CONTIGUOUS | yes | yes | NULL | F |
+-----------------------------------+-------+---------+------------+--------+
| .. c:macro:: PyBUF_ANY_CONTIGUOUS | yes | yes | NULL | C or F |
+-----------------------------------+-------+---------+------------+--------+
| .. c:macro:: PyBUF_ND | yes | NULL | NULL | C |
+-----------------------------------+-------+---------+------------+--------+
compound requests
~~~~~~~~~~~~~~~~~
All possible requests are fully defined by some combination of the flags in
the previous section. For convenience, the buffer protocol provides frequently
used combinations as single flags.
In the following table *U* stands for undefined contiguity. The consumer would
have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity.
.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|l|l|
+-------------------------------+-------+---------+------------+--------+----------+--------+
| Request | shape | strides | suboffsets | contig | readonly | format |
+===============================+=======+=========+============+========+==========+========+
| .. c:macro:: PyBUF_FULL | yes | yes | if needed | U | 0 | yes |
+-------------------------------+-------+---------+------------+--------+----------+--------+
| .. c:macro:: PyBUF_FULL_RO | yes | yes | if needed | U | 1 or 0 | yes |
+-------------------------------+-------+---------+------------+--------+----------+--------+
| .. c:macro:: PyBUF_RECORDS | yes | yes | NULL | U | 0 | yes |
+-------------------------------+-------+---------+------------+--------+----------+--------+
| .. c:macro:: PyBUF_RECORDS_RO | yes | yes | NULL | U | 1 or 0 | yes |
+-------------------------------+-------+---------+------------+--------+----------+--------+
| .. c:macro:: PyBUF_STRIDED | yes | yes | NULL | U | 0 | NULL |
+-------------------------------+-------+---------+------------+--------+----------+--------+
| .. c:macro:: PyBUF_STRIDED_RO | yes | yes | NULL | U | 1 or 0 | NULL |
+-------------------------------+-------+---------+------------+--------+----------+--------+
| .. c:macro:: PyBUF_CONTIG | yes | NULL | NULL | C | 0 | NULL |
+-------------------------------+-------+---------+------------+--------+----------+--------+
| .. c:macro:: PyBUF_CONTIG_RO | yes | NULL | NULL | C | 1 or 0 | NULL |
+-------------------------------+-------+---------+------------+--------+----------+--------+
Complex arrays
==============
NumPy-style: shape and strides
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The logical structure of NumPy-style arrays is defined by :c:member:`~Py_buffer.itemsize`,
:c:member:`~Py_buffer.ndim`, :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides`.
If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer.buf` is
interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In that case,
both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are *NULL*.
If :c:member:`~Py_buffer.strides` is *NULL*, the array is interpreted as
a standard n-dimensional C-array. Otherwise, the consumer must access an
n-dimensional array as follows:
``ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1]``
``item = *((typeof(item) *)ptr);``
As noted above, :c:member:`~Py_buffer.buf` can point to any location within
the actual memory block. An exporter can check the validity of a buffer with
this function:
.. code-block:: python
def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
"""Verify that the parameters represent a valid array within
the bounds of the allocated memory:
char *mem: start of the physical memory block
memlen: length of the physical memory block
offset: (char *)buf - mem
"""
if offset % itemsize:
return False
if offset < 0 or offset+itemsize > memlen:
return False
if any(v % itemsize for v in strides):
return False
if ndim <= 0:
return ndim == 0 and not shape and not strides
if 0 in shape:
return True
imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
if strides[j] <= 0)
imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
if strides[j] > 0)
return 0 <= offset+imin and offset+imax+itemsize <= memlen
PIL-style: shape, strides and suboffsets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In addition to the regular items, PIL-style arrays can contain pointers
that must be followed in order to get to the next element in a dimension.
For example, the regular three-dimensional C-array ``char v[2][2][3]`` can
also be viewed as an array of 2 pointers to 2 two-dimensional arrays:
``char (*v[2])[2][3]``. In suboffsets representation, those two pointers
can be embedded at the start of :c:member:`~Py_buffer.buf`, pointing
to two ``char x[2][3]`` arrays that can be located anywhere in memory.
Here is a function that returns a pointer to the element in an N-D array
pointed to by an N-dimensional index when there are both non-NULL strides
and suboffsets::
void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
Py_ssize_t *suboffsets, Py_ssize_t *indices) {
char *pointer = (char*)buf;
int i;
for (i = 0; i < ndim; i++) {
pointer += strides[i] * indices[i];
if (suboffsets[i] >=0 ) {
pointer = *((char**)pointer) + suboffsets[i];
}
}
return (void*)pointer;
}
Buffer-related functions
========================
.. c:function:: int PyObject_CheckBuffer(PyObject *obj)
Return 1 if *obj* supports the buffer interface otherwise 0. When 1 is
returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
succeed.
.. c:function:: int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)
Send a request to *exporter* to fill in *view* as specified by *flags*.
If the exporter cannot provide a buffer of the exact type, it MUST raise
:c:data:`PyExc_BufferError`, set :c:member:`view->obj` to *NULL* and
return -1.
On success, fill in *view*, set :c:member:`view->obj` to a new reference
to *exporter* and return 0. In the case of chained buffer providers
that redirect requests to a single object, :c:member:`view->obj` MAY
refer to this object instead of *exporter* (See :ref:`Buffer Object Structures <buffer-structs>`).
Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls
to :c:func:`PyBuffer_Release`, similar to :c:func:`malloc` and :c:func:`free`.
Thus, after the consumer is done with the buffer, :c:func:`PyBuffer_Release`
must be called exactly once.
.. c:function:: void PyBuffer_Release(Py_buffer *view)
Release the buffer *view* and decrement the reference count for
:c:member:`view->obj`. This function MUST be called when the buffer
is no longer being used, otherwise reference leaks may occur.
It is an error to call this function on a buffer that was not obtained via
:c:func:`PyObject_GetBuffer`.
.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer.format`.
This function is not yet implemented.
.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order)
Return 1 if the memory defined by the *view* is C-style (*order* is
``'C'``) or Fortran-style (*order* is ``'F'``) contiguous or either one
(*order* is ``'A'``). Return 0 otherwise.
.. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char order)
Fill the *strides* array with byte-strides of a contiguous (C-style if
*order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the
given shape with the given number of bytes per element.
.. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)
Handle buffer requests for an exporter that wants to expose *buf* of size *len*
with writability set according to *readonly*. *buf* is interpreted as a sequence
of unsigned bytes.
The *flags* argument indicates the request type. This function always fills in
*view* as specified by flags, unless *buf* has been designated as read-only
and :c:macro:`PyBUF_WRITABLE` is set in *flags*.
On success, set :c:member:`view->obj` to a new reference to *exporter* and
return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
:c:member:`view->obj` to *NULL* and return -1;
If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
*exporter* MUST be set to the exporting object. Otherwise, *exporter* MUST
be NULL.
Doc/c-api/bytearray.rst
+86
View File
@@ -0,0 +1,86 @@
.. highlightlang:: c
.. _bytearrayobjects:
Byte Array Objects
------------------
.. index:: object: bytearray
.. c:type:: PyByteArrayObject
This subtype of :c:type:`PyObject` represents a Python bytearray object.
.. c:var:: PyTypeObject PyByteArray_Type
This instance of :c:type:`PyTypeObject` represents the Python bytearray type;
it is the same object as :class:`bytearray` in the Python layer.
Type check macros
^^^^^^^^^^^^^^^^^
.. c:function:: int PyByteArray_Check(PyObject *o)
Return true if the object *o* is a bytearray object or an instance of a
subtype of the bytearray type.
.. c:function:: int PyByteArray_CheckExact(PyObject *o)
Return true if the object *o* is a bytearray object, but not an instance of a
subtype of the bytearray type.
Direct API functions
^^^^^^^^^^^^^^^^^^^^
.. c:function:: PyObject* PyByteArray_FromObject(PyObject *o)
Return a new bytearray object from any object, *o*, that implements the
:ref:`buffer protocol <bufferobjects>`.
.. XXX expand about the buffer protocol, at least somewhere
.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
Create a new bytearray object from *string* and its length, *len*. On
failure, *NULL* is returned.
.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
Concat bytearrays *a* and *b* and return a new bytearray with the result.
.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
Return the size of *bytearray* after checking for a *NULL* pointer.
.. c:function:: char* PyByteArray_AsString(PyObject *bytearray)
Return the contents of *bytearray* as a char array after checking for a
*NULL* pointer.
.. c:function:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)
Resize the internal buffer of *bytearray* to *len*.
Macros
^^^^^^
These macros trade safety for speed and they don't check pointers.
.. c:function:: char* PyByteArray_AS_STRING(PyObject *bytearray)
Macro version of :c:func:`PyByteArray_AsString`.
.. c:function:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
Macro version of :c:func:`PyByteArray_Size`.
Doc/c-api/bytes.rst
+194
View File
@@ -0,0 +1,194 @@
.. highlightlang:: c
.. _bytesobjects:
Bytes Objects
-------------
These functions raise :exc:`TypeError` when expecting a bytes parameter and are
called with a non-bytes parameter.
.. index:: object: bytes
.. c:type:: PyBytesObject
This subtype of :c:type:`PyObject` represents a Python bytes object.
.. c:var:: PyTypeObject PyBytes_Type
This instance of :c:type:`PyTypeObject` represents the Python bytes type; it
is the same object as :class:`bytes` in the Python layer.
.. c:function:: int PyBytes_Check(PyObject *o)
Return true if the object *o* is a bytes object or an instance of a subtype
of the bytes type.
.. c:function:: int PyBytes_CheckExact(PyObject *o)
Return true if the object *o* is a bytes object, but not an instance of a
subtype of the bytes type.
.. c:function:: PyObject* PyBytes_FromString(const char *v)
Return a new bytes object with a copy of the string *v* as value on success,
and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be
checked.
.. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
Return a new bytes object with a copy of the string *v* as value and length
*len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of
the bytes object are uninitialized.
.. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...)
Take a C :c:func:`printf`\ -style *format* string and a variable number of
arguments, calculate the size of the resulting Python bytes object and return
a bytes object with the values formatted into it. The variable arguments
must be C types and must correspond exactly to the format characters in the
*format* string. The following format characters are allowed:
.. % XXX: This should be exactly the same as the table in PyErr_Format.
.. % One should just refer to the other.
.. % XXX: 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.
.. tabularcolumns:: |l|l|L|
+-------------------+---------------+--------------------------------+
| Format Characters | Type | Comment |
+===================+===============+================================+
| :attr:`%%` | *n/a* | The literal % character. |
+-------------------+---------------+--------------------------------+
| :attr:`%c` | int | A single character, |
| | | represented as an C int. |
+-------------------+---------------+--------------------------------+
| :attr:`%d` | int | Exactly equivalent to |
| | | ``printf("%d")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%u` | unsigned int | Exactly equivalent to |
| | | ``printf("%u")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%ld` | long | Exactly equivalent to |
| | | ``printf("%ld")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%lu` | unsigned long | Exactly equivalent to |
| | | ``printf("%lu")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%zd` | Py_ssize_t | Exactly equivalent to |
| | | ``printf("%zd")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%zu` | size_t | Exactly equivalent to |
| | | ``printf("%zu")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%i` | int | Exactly equivalent to |
| | | ``printf("%i")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%x` | int | Exactly equivalent to |
| | | ``printf("%x")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%s` | char\* | A null-terminated C character |
| | | array. |
+-------------------+---------------+--------------------------------+
| :attr:`%p` | void\* | The hex representation of a C |
| | | pointer. Mostly equivalent to |
| | | ``printf("%p")`` except that |
| | | it is guaranteed to start with |
| | | the literal ``0x`` regardless |
| | | of what the platform's |
| | | ``printf`` yields. |
+-------------------+---------------+--------------------------------+
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.
.. c:function:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)
Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two
arguments.
.. c:function:: PyObject* PyBytes_FromObject(PyObject *o)
Return the bytes representation of object *o* that implements the buffer
protocol.
.. c:function:: Py_ssize_t PyBytes_Size(PyObject *o)
Return the length of the bytes in bytes object *o*.
.. c:function:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
Macro form of :c:func:`PyBytes_Size` but without error checking.
.. c:function:: char* PyBytes_AsString(PyObject *o)
Return a NUL-terminated representation of the contents of *o*. The pointer
refers to the internal buffer of *o*, not a copy. The data must not be
modified in any way, unless the string was just created using
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*o* is not a string object at all, :c:func:`PyBytes_AsString` returns *NULL*
and raises :exc:`TypeError`.
.. c:function:: char* PyBytes_AS_STRING(PyObject *string)
Macro form of :c:func:`PyBytes_AsString` but without error checking.
.. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
Return a NUL-terminated representation of the contents of the object *obj*
through the output variables *buffer* and *length*.
If *length* is *NULL*, the resulting buffer may not contain NUL characters;
if it does, the function returns ``-1`` and a :exc:`TypeError` is raised.
The buffer refers to an internal string buffer of *obj*, not a copy. The data
must not be modified in any way, unless the string was just created using
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*string* is not a string object at all, :c:func:`PyBytes_AsStringAndSize`
returns ``-1`` and raises :exc:`TypeError`.
.. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
Create a new bytes object in *\*bytes* containing the contents of *newpart*
appended to *bytes*; the caller will own the new reference. The reference to
the old value of *bytes* will be stolen. If the new string cannot be
created, the old reference to *bytes* will still be discarded and the value
of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
Create a new string object in *\*bytes* containing the contents of *newpart*
appended to *bytes*. This version decrements the reference count of
*newpart*.
.. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
A way to resize a bytes object even though it is "immutable". Only use this
to build up a brand new bytes object; don't use this if the bytes may already
be known in other parts of the code. It is an error to call this function if
the refcount on the input bytes object is not one. Pass the address of an
existing bytes object as an lvalue (it may be written into), and the new size
desired. On success, *\*bytes* holds the resized bytes object and ``0`` is
returned; the address in *\*bytes* may differ from its input value. If the
reallocation fails, the original bytes object at *\*bytes* is deallocated,
*\*bytes* is set to *NULL*, a memory exception is set, and ``-1`` is
returned.
Doc/c-api/capsule.rst
+150
View File
@@ -0,0 +1,150 @@
.. highlightlang:: c
.. _capsules:
Capsules
--------
.. index:: object: Capsule
Refer to :ref:`using-capsules` for more information on using these objects.
.. c:type:: PyCapsule
This subtype of :c:type:`PyObject` represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a :c:type:`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.
.. c:type:: PyCapsule_Destructor
The type of a destructor callback for a capsule. Defined as::
typedef void (*PyCapsule_Destructor)(PyObject *);
See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor
callbacks.
.. c:function:: int PyCapsule_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyCapsule`.
.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer*
argument may not be *NULL*.
On failure, set an exception and return *NULL*.
The *name* string may either be *NULL* or a pointer to a valid C string. If
non-*NULL*, this string must outlive the capsule. (Though it is permitted to
free it inside the *destructor*.)
If the *destructor* argument is not *NULL*, it will be called with the
capsule as its argument when it is destroyed.
If this capsule will be stored as an attribute of a module, the *name* should
be specified as ``modulename.attributename``. This will enable other modules
to import the capsule using :c:func:`PyCapsule_Import`.
.. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)
Retrieve the *pointer* stored in the capsule. On failure, set an exception
and return *NULL*.
The *name* parameter must compare exactly to the name stored in the capsule.
If the name stored in the capsule is *NULL*, the *name* passed in must also
be *NULL*. Python uses the C function :c:func:`strcmp` to compare capsule
names.
.. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
Return the current destructor stored in the capsule. On failure, set an
exception and return *NULL*.
It is legal for a capsule to have a *NULL* destructor. This makes a *NULL*
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: void* PyCapsule_GetContext(PyObject *capsule)
Return the current context stored in the capsule. On failure, set an
exception and return *NULL*.
It is legal for a capsule to have a *NULL* context. This makes a *NULL*
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: const char* PyCapsule_GetName(PyObject *capsule)
Return the current name stored in the capsule. On failure, set an exception
and return *NULL*.
It is legal for a capsule to have a *NULL* name. This makes a *NULL* return
code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: void* PyCapsule_Import(const char *name, int no_block)
Import a pointer to a C object from a capsule attribute in a module. The
*name* parameter should specify the full name to the attribute, as in
``module.attribute``. The *name* stored in the capsule must match this
string exactly. If *no_block* is true, import the module without blocking
(using :c:func:`PyImport_ImportModuleNoBlock`). If *no_block* is false,
import the module conventionally (using :c:func:`PyImport_ImportModule`).
Return the capsule's internal *pointer* on success. On failure, set an
exception and return *NULL*. However, if :c:func:`PyCapsule_Import` failed to
import the module, and *no_block* was true, no exception is set.
.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
Determines whether or not *capsule* is a valid capsule. A valid capsule is
non-*NULL*, passes :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer
stored in it, and its internal name matches the *name* parameter. (See
:c:func:`PyCapsule_GetPointer` for information on how capsule names are
compared.)
In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to
any of the accessors (any function starting with :c:func:`PyCapsule_Get`) are
guaranteed to succeed.
Return a nonzero value if the object is valid and matches the name passed in.
Return 0 otherwise. This function will not fail.
.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
Set the context pointer inside *capsule* to *context*.
Return 0 on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
Set the destructor inside *capsule* to *destructor*.
Return 0 on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
Set the name inside *capsule* to *name*. If non-*NULL*, the name must
outlive the capsule. If the previous *name* stored in the capsule was not
*NULL*, no attempt is made to free it.
Return 0 on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
Set the void pointer inside *capsule* to *pointer*. The pointer may not be
*NULL*.
Return 0 on success. Return nonzero and set an exception on failure.
Doc/c-api/cell.rst
+62
View File
@@ -0,0 +1,62 @@
.. highlightlang:: c
.. _cell-objects:
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.
.. c:type:: PyCellObject
The C structure used for cell objects.
.. c:var:: PyTypeObject PyCell_Type
The type object corresponding to cell objects.
.. c:function:: int PyCell_Check(ob)
Return true if *ob* is a cell object; *ob* must not be *NULL*.
.. c:function:: PyObject* PyCell_New(PyObject *ob)
Create and return a new cell object containing the value *ob*. The parameter may
be *NULL*.
.. c:function:: PyObject* PyCell_Get(PyObject *cell)
Return the contents of the cell *cell*.
.. c:function:: PyObject* PyCell_GET(PyObject *cell)
Return the contents of the cell *cell*, but without checking that *cell* is
non-*NULL* and a cell object.
.. c:function:: int PyCell_Set(PyObject *cell, PyObject *value)
Set the contents of the cell object *cell* to *value*. This releases the
reference to any current content of the cell. *value* may be *NULL*. *cell*
must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On
success, ``0`` will be returned.
.. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)
Sets the value of the cell object *cell* to *value*. No reference counts are
adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
be a cell object.

Some files were not shown because too many files have changed in this diff Show More