Mercurial > cpython-lru_cache-weakref

annotate Doc/api/utilities.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents fed8a18894f5
children 4c67dd42a1d9 e24b8d0b6470
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \chapter{Utilities \label{utilities}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3 The functions in this chapter perform various utility tasks, ranging
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 from helping C code be more portable across platforms, using Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 modules from C, and parsing function arguments and constructing Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 values from C values.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9 \section{Operating System Utilities \label{os}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 \begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12 Return true (nonzero) if the standard I/O file \var{fp} with name
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13 \var{filename} is deemed interactive. This is the case for files
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14 for which \samp{isatty(fileno(\var{fp}))} is true. If the global
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15 flag \cdata{Py_InteractiveFlag} is true, this function also returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16 true if the \var{filename} pointer is \NULL{} or if the name is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17 equal to one of the strings \code{'<stdin>'} or \code{'???'}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20 \begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21 Return the time of last modification of the file \var{filename}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 The result is encoded in the same way as the timestamp returned by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23 the standard C library function \cfunction{time()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26 \begin{cfuncdesc}{void}{PyOS_AfterFork}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27 Function to update some internal state after a process fork; this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28 should be called in the new process if the Python interpreter will
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29 continue to be used. If a new executable is loaded into the new
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 process, this function does not need to be called.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33 \begin{cfuncdesc}{int}{PyOS_CheckStack}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34 Return true when the interpreter runs out of stack space. This is a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35 reliable check, but is only available when \constant{USE_STACKCHECK}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 is defined (currently on Windows using the Microsoft Visual \Cpp{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 compiler and on the Macintosh). \constant{USE_CHECKSTACK} will be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38 defined automatically; you should never change the definition in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39 your own code.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42 \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43 Return the current signal handler for signal \var{i}. This is a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 thin wrapper around either \cfunction{sigaction()} or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45 \cfunction{signal()}. Do not call those functions directly!
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46 \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
47 (*)(int)}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
48 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50 \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 Set the signal handler for signal \var{i} to be \var{h}; return the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52 old signal handler. This is a thin wrapper around either
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 \cfunction{sigaction()} or \cfunction{signal()}. Do not call those
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 functions directly! \ctype{PyOS_sighandler_t} is a typedef alias
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 for \ctype{void (*)(int)}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59 \section{Process Control \label{processControl}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 \begin{cfuncdesc}{void}{Py_FatalError}{char *message}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62 Print a fatal error message and kill the process. No cleanup is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 performed. This function should only be invoked when a condition is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64 detected that would make it dangerous to continue using the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 interpreter; e.g., when the object administration appears to be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 corrupted. On \UNIX, the standard C library function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 \cfunction{abort()}\ttindex{abort()} is called which will attempt to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68 produce a \file{core} file.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 \begin{cfuncdesc}{void}{Py_Exit}{int status}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 Exit the current process. This calls
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and then calls the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74 standard C library function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 \code{exit(\var{status})}\ttindex{exit()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
77
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 \begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 Register a cleanup function to be called by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}. The cleanup
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81 function will be called with no arguments and should return no
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 value. At most 32 \index{cleanup functions}cleanup functions can be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83 registered. When the registration is successful,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 \cfunction{Py_AtExit()} returns \code{0}; on failure, it returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85 \code{-1}. The cleanup function registered last is called first.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86 Each cleanup function will be called at most once. Since Python's
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87 internal finallization will have completed before the cleanup
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88 function, no Python APIs should be called by \var{func}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
90
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
92 \section{Importing Modules \label{importing}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
94 \begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{char *name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95 This is a simplified interface to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96 \cfunction{PyImport_ImportModuleEx()} below, leaving the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
97 \var{globals} and \var{locals} arguments set to \NULL. When the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98 \var{name} argument contains a dot (when it specifies a submodule of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
99 a package), the \var{fromlist} argument is set to the list
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
100 \code{['*']} so that the return value is the named module rather
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
101 than the top-level package containing it as would otherwise be the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
102 case. (Unfortunately, this has an additional side effect when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 \var{name} in fact specifies a subpackage instead of a submodule:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104 the submodules specified in the package's \code{__all__} variable
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
105 are \index{package variable!\code{__all__}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
106 \withsubitem{(package variable)}{\ttindex{__all__}}loaded.) Return
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107 a new reference to the imported module, or \NULL{} with an exception
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108 set on failure (the module may still be created in this case ---
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109 examine \code{sys.modules} to find out).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 \withsubitem{(in module sys)}{\ttindex{modules}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113 \begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 PyObject *globals, PyObject *locals, PyObject *fromlist}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115 Import a module. This is best described by referring to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
116 built-in Python function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117 \function{__import__()}\bifuncindex{__import__}, as the standard
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
118 \function{__import__()} function calls this function directly.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
119
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 The return value is a new reference to the imported module or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121 top-level package, or \NULL{} with an exception set on failure (the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
122 module may still be created in this case). Like for
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
123 \function{__import__()}, the return value when a submodule of a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
124 package was requested is normally the top-level package, unless a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 non-empty \var{fromlist} was given.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128 \begin{cfuncdesc}{PyObject*}{PyImport_Import}{PyObject *name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
129 This is a higher-level interface that calls the current ``import
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
130 hook function''. It invokes the \function{__import__()} function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131 from the \code{__builtins__} of the current globals. This means
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
132 that the import is done using whatever import hooks are installed in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
133 the current environment, e.g. by \module{rexec}\refstmodindex{rexec}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
134 or \module{ihooks}\refstmodindex{ihooks}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
135 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
136
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
137 \begin{cfuncdesc}{PyObject*}{PyImport_ReloadModule}{PyObject *m}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
138 Reload a module. This is best described by referring to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
139 built-in Python function \function{reload()}\bifuncindex{reload}, as
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
140 the standard \function{reload()} function calls this function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
141 directly. Return a new reference to the reloaded module, or \NULL{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
142 with an exception set on failure (the module still exists in this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
143 case).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
144 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
145
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
146 \begin{cfuncdesc}{PyObject*}{PyImport_AddModule}{char *name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
147 Return the module object corresponding to a module name. The
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
148 \var{name} argument may be of the form \code{package.module}).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
149 First check the modules dictionary if there's one there, and if not,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
150 create a new one and insert in in the modules dictionary.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
151 \note{This function does not load or import the module; if the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
152 module wasn't already loaded, you will get an empty module object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
153 Use \cfunction{PyImport_ImportModule()} or one of its variants to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
154 import a module. Return \NULL{} with an exception set on failure.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
155 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
156
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
157 \begin{cfuncdesc}{PyObject*}{PyImport_ExecCodeModule}{char *name, PyObject *co}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
158 Given a module name (possibly of the form \code{package.module}) and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
159 a code object read from a Python bytecode file or obtained from the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
160 built-in function \function{compile()}\bifuncindex{compile}, load
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
161 the module. Return a new reference to the module object, or \NULL{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
162 with an exception set if an error occurred (the module may still be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
163 created in this case). (This function would reload the module if it
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164 was already imported.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
166
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
167 \begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168 Return the magic number for Python bytecode files
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
169 (a.k.a. \file{.pyc} and \file{.pyo} files). The magic number should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170 be present in the first four bytes of the bytecode file, in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171 little-endian byte order.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
172 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
173
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174 \begin{cfuncdesc}{PyObject*}{PyImport_GetModuleDict}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175 Return the dictionary used for the module administration
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
176 (a.k.a.\ \code{sys.modules}). Note that this is a per-interpreter
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
177 variable.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
178 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
179
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
180 \begin{cfuncdesc}{void}{_PyImport_Init}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
181 Initialize the import mechanism. For internal use only.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
182 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
183
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
184 \begin{cfuncdesc}{void}{PyImport_Cleanup}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
185 Empty the module table. For internal use only.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
186 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
187
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
188 \begin{cfuncdesc}{void}{_PyImport_Fini}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
189 Finalize the import mechanism. For internal use only.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
190 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
191
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
192 \begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
193 For internal use only.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
194 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
195
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
196 \begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
197 For internal use only.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
198 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
199
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
200 \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
201 Load a frozen module named \var{name}. Return \code{1} for success,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
202 \code{0} if the module is not found, and \code{-1} with an exception
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
203 set if the initialization failed. To access the imported module on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
204 a successful load, use \cfunction{PyImport_ImportModule()}. (Note
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
205 the misnomer --- this function would reload the module if it was
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
206 already imported.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
207 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
208
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
209 \begin{ctypedesc}[_frozen]{struct _frozen}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
210 This is the structure type definition for frozen module descriptors,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
211 as generated by the \program{freeze}\index{freeze utility} utility
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
212 (see \file{Tools/freeze/} in the Python source distribution). Its
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
213 definition, found in \file{Include/import.h}, is:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
214
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
215 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
216 struct _frozen {
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
217 char *name;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
218 unsigned char *code;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
219 int size;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
220 };
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
221 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
222 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
223
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
224 \begin{cvardesc}{struct _frozen*}{PyImport_FrozenModules}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
225 This pointer is initialized to point to an array of \ctype{struct
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
226 _frozen} records, terminated by one whose members are all \NULL{} or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
227 zero. When a frozen module is imported, it is searched in this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
228 table. Third-party code could play tricks with this to provide a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
229 dynamically created collection of frozen modules.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
230 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
231
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
232 \begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
233 void (*initfunc)(void)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
234 Add a single module to the existing table of built-in modules. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
235 is a convenience wrapper around
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
236 \cfunction{PyImport_ExtendInittab()}, returning \code{-1} if the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
237 table could not be extended. The new module can be imported by the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
238 name \var{name}, and uses the function \var{initfunc} as the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
239 initialization function called on the first attempted import. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
240 should be called before \cfunction{Py_Initialize()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
241 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
242
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
243 \begin{ctypedesc}[_inittab]{struct _inittab}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
244 Structure describing a single entry in the list of built-in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
245 modules. Each of these structures gives the name and initialization
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
246 function for a module built into the interpreter. Programs which
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
247 embed Python may use an array of these structures in conjunction
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
248 with \cfunction{PyImport_ExtendInittab()} to provide additional
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
249 built-in modules. The structure is defined in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
250 \file{Include/import.h} as:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
251
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
252 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
253 struct _inittab {
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
254 char *name;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
255 void (*initfunc)(void);
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
256 };
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
257 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
258 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
259
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
260 \begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
261 Add a collection of modules to the table of built-in modules. The
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
262 \var{newtab} array must end with a sentinel entry which contains
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
263 \NULL{} for the \member{name} field; failure to provide the sentinel
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
264 value can result in a memory fault. Returns \code{0} on success or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
265 \code{-1} if insufficient memory could be allocated to extend the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
266 internal table. In the event of failure, no modules are added to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
267 the internal table. This should be called before
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
268 \cfunction{Py_Initialize()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
269 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
270
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
271
20425
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
272 \section{Data marshalling support \label{marshalling-utils}}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
273
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
274 These routines allow C code to work with serialized objects using the
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
275 same data format as the \module{marshal} module. There are functions
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
276 to write data into the serialization format, and additional functions
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
277 that can be used to read the data back. Files used to store marshalled
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
278 data must be opened in binary mode.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
279
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
280 Numeric values are stored with the least significant byte first.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
281
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
282 \begin{cfuncdesc}{void}{PyMarshal_WriteLongToFile}{long value, FILE *file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
283 Marshal a \ctype{long} integer, \var{value}, to \var{file}. This
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
284 will only write the least-significant 32 bits of \var{value};
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
285 regardless of the size of the native \ctype{long} type.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
286 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
287
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
288 \begin{cfuncdesc}{void}{PyMarshal_WriteShortToFile}{short value, FILE *file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
289 Marshal a \ctype{short} integer, \var{value}, to \var{file}.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
290 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
291
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
292 \begin{cfuncdesc}{void}{PyMarshal_WriteObjectToFile}{PyObject *value,
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
293 FILE *file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
294 Marshal a Python object, \var{value}, to \var{file}. This
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
295 will only write the least-significant 16 bits of \var{value};
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
296 regardless of the size of the native \ctype{short} type.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
297 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
298
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
299 \begin{cfuncdesc}{PyObject*}{PyMarshal_WriteObjectToString}{PyObject *value}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
300 Return a string object containing the marshalled representation of
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
301 \var{value}.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
302 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
303
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
304 The following functions allow marshalled values to be read back in.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
305
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
306 XXX What about error detection? It appears that reading past the end
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
307 of the file will always result in a negative numeric value (where
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
308 that's relevant), but it's not clear that negative values won't be
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
309 handled properly when there's no error. What's the right way to tell?
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
310 Should only non-negative values be written using these routines?
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
311
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
312 \begin{cfuncdesc}{long}{PyMarshal_ReadLongFromFile}{FILE *file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
313 Return a C \ctype{long} from the data stream in a \ctype{FILE*}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
314 opened for reading. Only a 32-bit value can be read in using
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
315 this function, regardless of the native size of \ctype{long}.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
316 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
317
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
318 \begin{cfuncdesc}{int}{PyMarshal_ReadShortFromFile}{FILE *file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
319 Return a C \ctype{short} from the data stream in a \ctype{FILE*}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
320 opened for reading. Only a 16-bit value can be read in using
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
321 this function, regardless of the native size of \ctype{long}.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
322 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
323
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
324 \begin{cfuncdesc}{PyObject*}{PyMarshal_ReadObjectFromFile}{FILE *file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
325 Return a Python object from the data stream in a \ctype{FILE*}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
326 opened for reading. On error, sets the appropriate exception
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
327 (\exception{EOFError} or \exception{TypeError}) and returns \NULL.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
328 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
329
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
330 \begin{cfuncdesc}{PyObject*}{PyMarshal_ReadLastObjectFromFile}{FILE *file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
331 Return a Python object from the data stream in a \ctype{FILE*}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
332 opened for reading. Unlike
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
333 \cfunction{PyMarshal_ReadObjectFromFile()}, this function assumes
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
334 that no further objects will be read from the file, allowing it to
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
335 aggressively load file data into memory so that the de-serialization
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
336 can operate from data in memory rather than reading a byte at a time
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
337 from the file. Only use these variant if you are certain that you
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
338 won't be reading anything else from the file. On error, sets the
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
339 appropriate exception (\exception{EOFError} or
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
340 \exception{TypeError}) and returns \NULL.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
341 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
342
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
343 \begin{cfuncdesc}{PyObject*}{PyMarshal_ReadObjectFromString}{char *string,
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
344 int len}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
345 Return a Python object from the data stream in a character buffer
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
346 containing \var{len} bytes pointed to by \var{string}. On error,
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
347 sets the appropriate exception (\exception{EOFError} or
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
348 \exception{TypeError}) and returns \NULL.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
349 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
350
7d1f490b6cb1 Added documentation for the functions listed in marshal.h.
Fred Drake <fdrake@acm.org>
parents: 20390
diff changeset
351
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
352 \section{Parsing arguments and building values
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
353 \label{arg-parsing}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
354
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
355 These functions are useful when creating your own extensions functions
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
356 and methods. Additional information and examples are available in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
357 \citetitle[../ext/ext.html]{Extending and Embedding the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
358 Interpreter}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
359
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
360 \begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
361 \moreargs}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
362 Parse the parameters of a function that takes only positional
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
363 parameters into local variables. Returns true on success; on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
364 failure, it returns false and raises the appropriate exception. See
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
365 \citetitle[../ext/parseTuple.html]{Extending and Embedding the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
366 Python Interpreter} for more information.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
367 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
368
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
369 \begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
370 PyObject *kw, char *format, char *keywords[],
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
371 \moreargs}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
372 Parse the parameters of a function that takes both positional and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
373 keyword parameters into local variables. Returns true on success;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
374 on failure, it returns false and raises the appropriate exception.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
375 See \citetitle[../ext/parseTupleAndKeywords.html]{Extending and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
376 Embedding the Python Interpreter} for more information.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
377 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
378
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
379 \begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, char *format,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
380 \moreargs}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
381 Function used to deconstruct the argument lists of ``old-style''
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
382 functions --- these are functions which use the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
383 \constant{METH_OLDARGS} parameter parsing method. This is not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
384 recommended for use in parameter parsing in new code, and most code
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
385 in the standard interpreter has been modified to no longer use this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
386 for that purpose. It does remain a convenient way to decompose
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
387 other tuples, however, and may continue to be used for that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
388 purpose.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
389 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
390
20633
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
391 \begin{cfuncdesc}{int}{PyArg_UnpackTuple}{PyObject *args, char *name,
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
392 int min, int max, \moreargs}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
393 A simpler form of parameter retrieval which does not use a format
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
394 string to specify the types of the arguments. Functions which use
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
395 this method to retrieve their parameters should be declared as
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
396 \constant{METH_VARARGS} in function or method tables. The tuple
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
397 containing the actual parameters should be passed as \var{args}; it
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
398 must actually be a tuple. The length of the tuple must be at least
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
399 \var{min} and no more than \var{max}; \var{min} and \var{max} may be
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
400 equal. Additional arguments must be passed to the function, each of
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
401 which should be a pointer to a \ctype{PyObject*} variable; these
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
402 will be filled in with the values from \var{args}; they will contain
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
403 borrowed references. The variables which correspond to optional
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
404 parameters not given by \var{args} will not be filled in; these
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
405 should be initialized by the caller.
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
406 This function returns true on success and false if \var{args} is not
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
407 a tuple or contains the wrong number of elements; an exception will
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
408 be set if there was a failure.
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
409
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
410 This is an example of the use of this function, taken from the
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
411 sources for the \module{_weakref} helper module for weak references:
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
412
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
413 \begin{verbatim}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
414 static PyObject *
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
415 weakref_ref(PyObject *self, PyObject *args)
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
416 {
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
417 PyObject *object;
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
418 PyObject *callback = NULL;
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
419 PyObject *result = NULL;
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
420
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
421 if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
422 result = PyWeakref_NewRef(object, callback);
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
423 }
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
424 return result;
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
425 }
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
426 \end{verbatim}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
427
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
428 The call to \cfunction{PyArg_UnpackTuple()} in this example is
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
429 entirely equivalent to this call to \cfunction{PyArg_ParseTuple()}:
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
430
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
431 \begin{verbatim}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
432 PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
433 \end{verbatim}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
434
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
435 \versionadded{2.2}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
436 \end{cfuncdesc}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function.
Fred Drake <fdrake@acm.org>
parents: 20425
diff changeset
437
20390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
438 \begin{cfuncdesc}{PyObject*}{Py_BuildValue}{char *format,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
439 \moreargs}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
440 Create a new value based on a format string similar to those
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
441 accepted by the \cfunction{PyArg_Parse*()} family of functions and a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
442 sequence of values. Returns the value or \NULL{} in the case of an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
443 error; an exception will be raised if \NULL{} is returned. For more
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
444 information on the format string and additional parameters, see
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
445 \citetitle[../ext/buildValue.html]{Extending and Embedding the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
446 Python Interpreter}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
447 \end{cfuncdesc}