Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 4de05a9

Browse files
freddrakefreddrake
committed
Place C typedef for Py_complex after brief description, to be more consistent
with the other example of a structure description (struct _frozen). Added index entries for the modules referenced in the document.
1 parent 53fb772 commit 4de05a9

2 files changed

Lines changed: 84 additions & 64 deletions

File tree

‎Doc/api.tex‎

Lines changed: 42 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -479,9 +479,10 @@ \section{Embedding Python}
479479

480480
The basic initialization function is \cfunction{Py_Initialize()}.
481481
This initializes the table of loaded modules, and creates the
482-
fundamental modules \module{__builtin__}, \module{__main__} and
483-
\module{sys}. It also initializes the module search path
484-
(\code{sys.path}).
482+
fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
483+
\module{__main__}\refbimodindex{__main__} and
484+
\module{sys}\refbimodindex{sys}. It also initializes the module
485+
search path (\code{sys.path}).
485486

486487
\cfunction{Py_Initialize()} does not set the ``script argument list''
487488
(\code{sys.argv}). If this variable is needed by Python code that
@@ -772,10 +773,11 @@ \chapter{Exception Handling}
772773
\begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
773774
This function interacts with Python's signal handling. It checks
774775
whether a signal has been sent to the processes and if so, invokes the
775-
corresponding signal handler. If the \module{signal} module is
776-
supported, this can invoke a signal handler written in Python. In all
777-
cases, the default effect for \constant{SIGINT} is to raise the
778-
\exception{KeyboadInterrupt} exception. If an exception is raised the
776+
corresponding signal handler. If the
777+
\module{signal}\refbimodindex{signal} module is supported, this can
778+
invoke a signal handler written in Python. In all cases, the default
779+
effect for \constant{SIGINT} is to raise the
780+
\exception{KeyboadInterrupt} exception. If an exception is raised the
779781
error indicator is set and the function returns \code{1}; otherwise
780782
the function returns \code{0}. The error indicator may or may not be
781783
cleared if it was previously set.
@@ -935,7 +937,8 @@ \section{Importing Modules}
935937
function''. It invokes the \function{__import__()} function from the
936938
\code{__builtins__} of the current globals. This means that the
937939
import is done using whatever import hooks are installed in the
938-
current environment, e.g. by \module{rexec} or \module{ihooks}.
940+
current environment, e.g. by \module{rexec}\refstmodindex{rexec} or
941+
\module{ihooks}\refstmodindex{ihooks}.
939942
\end{cfuncdesc}
940943
941944
\begin{cfuncdesc}{PyObject *}{PyImport_ReloadModule}{PyObject *m}
@@ -2077,17 +2080,17 @@ \subsection{Floating Point Objects}
20772080
\subsection{Complex Number Objects}
20782081
20792082
\begin{ctypedesc}{Py_complex}
2083+
The \C{} structure which corresponds to the value portion of a Python
2084+
complex number object. Most of the functions for dealing with complex
2085+
number objects use structures of this type as input or output values,
2086+
as appropriate. It is defined as:
2087+
20802088
\begin{verbatim}
20812089
typedef struct {
20822090
double real;
20832091
double imag;
2084-
}
2092+
} Py_complex;
20852093
\end{verbatim}
2086-
2087-
The \C{} structure which corresponds to the value portion of a Python
2088-
complex number object. Most of the functions for dealing with complex
2089-
number objects use structures of this type as input or output values,
2090-
as appropriate.
20912094
\end{ctypedesc}
20922095
20932096
\begin{ctypedesc}{PyComplexObject}
@@ -2226,10 +2229,13 @@ \chapter{Initialization, Finalization, and Threads}
22262229
\cfunction{PyEval_InitThreads()}, \cfunction{PyEval_ReleaseLock()},
22272230
and \cfunction{PyEval_AcquireLock()}. This initializes the table of
22282231
loaded modules (\code{sys.modules}), and creates the fundamental
2229-
modules \module{__builtin__}, \module{__main__} and \module{sys}. It
2230-
also initializes the module search path (\code{sys.path}). It does
2231-
not set \code{sys.argv}; use \cfunction{PySys_SetArgv()} for that.
2232-
This is a no-op when called for a second time (without calling
2232+
modules \module{__builtin__}\refbimodindex{__builtin__},
2233+
\module{__main__}\refbimodindex{__main__} and
2234+
\module{sys}\refbimodindex{sys}. It also initializes the module
2235+
search path (\code{sys.path}).%
2236+
\indexiii{module}{search}{path}
2237+
It does not set \code{sys.argv}; use \cfunction{PySys_SetArgv()} for
2238+
that. This is a no-op when called for a second time (without calling
22332239
\cfunction{Py_Finalize()} first). There is no return value; it is a
22342240
fatal error if the initialization fails.
22352241
\end{cfuncdesc}
@@ -2277,15 +2283,17 @@ \chapter{Initialization, Finalization, and Threads}
22772283
22782284
\begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
22792285
\strong{(NEW in 1.5a3!)}
2280-
Create a new sub-interpreter. This is an (almost) totally separate
2281-
environment for the execution of Python code. In particular, the new
2282-
interpreter has separate, independent versions of all imported
2283-
modules, including the fundamental modules \module{__builtin__},
2284-
\module{__main__} and \module{sys}. The table of loaded modules
2285-
(\code{sys.modules}) and the module search path (\code{sys.path}) are
2286-
also separate. The new environment has no \code{sys.argv} variable.
2287-
It has new standard I/O stream file objects \code{sys.stdin},
2288-
\code{sys.stdout} and \code{sys.stderr} (however these refer to the
2286+
Create a new sub-interpreter. This is an (almost) totally separate
2287+
environment for the execution of Python code. In particular, the new
2288+
interpreter has separate, independent versions of all imported
2289+
modules, including the fundamental modules
2290+
\module{__builtin__}\refbimodindex{__builtin__},
2291+
\module{__main__}\refbimodindex{__main__} and
2292+
\module{sys}\refbimodindex{sys}. The table of loaded modules
2293+
(\code{sys.modules}) and the module search path (\code{sys.path}) are
2294+
also separate. The new environment has no \code{sys.argv} variable.
2295+
It has new standard I/O stream file objects \code{sys.stdin},
2296+
\code{sys.stdout} and \code{sys.stderr} (however these refer to the
22892297
same underlying \code{FILE} structures in the \C{} library).
22902298
22912299
The return value points to the first thread state created in the new
@@ -2423,6 +2431,7 @@ \chapter{Initialization, Finalization, and Threads}
24232431
\end{cfuncdesc}
24242432
24252433
\begin{cfuncdesc}{char *}{Py_GetPath}{}
2434+
\indexiii{module}{search}{path}
24262435
Return the default module search path; this is computed from the
24272436
program name (set by \cfunction{Py_SetProgramName()} above) and some
24282437
environment variables. The returned string consists of a series of
@@ -2672,11 +2681,12 @@ \section{Thread State and the Global Interpreter Lock}
26722681
lock is not created initially. This situation is equivalent to having
26732682
acquired the lock: when there is only a single thread, all object
26742683
accesses are safe. Therefore, when this function initializes the
2675-
lock, it also acquires it. Before the Python \module{thread} module
2676-
creates a new thread, knowing that either it has the lock or the lock
2677-
hasn't been created yet, it calls \cfunction{PyEval_InitThreads()}.
2678-
When this call returns, it is guaranteed that the lock has been
2679-
created and that it has acquired it.
2684+
lock, it also acquires it. Before the Python
2685+
\module{thread}\refbimodindex{thread} module creates a new thread,
2686+
knowing that either it has the lock or the lock hasn't been created
2687+
yet, it calls \cfunction{PyEval_InitThreads()}. When this call
2688+
returns, it is guaranteed that the lock has been created and that it
2689+
has acquired it.
26802690
26812691
It is \strong{not} safe to call this function when it is unknown which
26822692
thread (if any) currently has the global interpreter lock.

‎Doc/api/api.tex‎

Lines changed: 42 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -479,9 +479,10 @@ \section{Embedding Python}
479479

480480
The basic initialization function is \cfunction{Py_Initialize()}.
481481
This initializes the table of loaded modules, and creates the
482-
fundamental modules \module{__builtin__}, \module{__main__} and
483-
\module{sys}. It also initializes the module search path
484-
(\code{sys.path}).
482+
fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
483+
\module{__main__}\refbimodindex{__main__} and
484+
\module{sys}\refbimodindex{sys}. It also initializes the module
485+
search path (\code{sys.path}).
485486

486487
\cfunction{Py_Initialize()} does not set the ``script argument list''
487488
(\code{sys.argv}). If this variable is needed by Python code that
@@ -772,10 +773,11 @@ \chapter{Exception Handling}
772773
\begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
773774
This function interacts with Python's signal handling. It checks
774775
whether a signal has been sent to the processes and if so, invokes the
775-
corresponding signal handler. If the \module{signal} module is
776-
supported, this can invoke a signal handler written in Python. In all
777-
cases, the default effect for \constant{SIGINT} is to raise the
778-
\exception{KeyboadInterrupt} exception. If an exception is raised the
776+
corresponding signal handler. If the
777+
\module{signal}\refbimodindex{signal} module is supported, this can
778+
invoke a signal handler written in Python. In all cases, the default
779+
effect for \constant{SIGINT} is to raise the
780+
\exception{KeyboadInterrupt} exception. If an exception is raised the
779781
error indicator is set and the function returns \code{1}; otherwise
780782
the function returns \code{0}. The error indicator may or may not be
781783
cleared if it was previously set.
@@ -935,7 +937,8 @@ \section{Importing Modules}
935937
function''. It invokes the \function{__import__()} function from the
936938
\code{__builtins__} of the current globals. This means that the
937939
import is done using whatever import hooks are installed in the
938-
current environment, e.g. by \module{rexec} or \module{ihooks}.
940+
current environment, e.g. by \module{rexec}\refstmodindex{rexec} or
941+
\module{ihooks}\refstmodindex{ihooks}.
939942
\end{cfuncdesc}
940943
941944
\begin{cfuncdesc}{PyObject *}{PyImport_ReloadModule}{PyObject *m}
@@ -2077,17 +2080,17 @@ \subsection{Floating Point Objects}
20772080
\subsection{Complex Number Objects}
20782081
20792082
\begin{ctypedesc}{Py_complex}
2083+
The \C{} structure which corresponds to the value portion of a Python
2084+
complex number object. Most of the functions for dealing with complex
2085+
number objects use structures of this type as input or output values,
2086+
as appropriate. It is defined as:
2087+
20802088
\begin{verbatim}
20812089
typedef struct {
20822090
double real;
20832091
double imag;
2084-
}
2092+
} Py_complex;
20852093
\end{verbatim}
2086-
2087-
The \C{} structure which corresponds to the value portion of a Python
2088-
complex number object. Most of the functions for dealing with complex
2089-
number objects use structures of this type as input or output values,
2090-
as appropriate.
20912094
\end{ctypedesc}
20922095
20932096
\begin{ctypedesc}{PyComplexObject}
@@ -2226,10 +2229,13 @@ \chapter{Initialization, Finalization, and Threads}
22262229
\cfunction{PyEval_InitThreads()}, \cfunction{PyEval_ReleaseLock()},
22272230
and \cfunction{PyEval_AcquireLock()}. This initializes the table of
22282231
loaded modules (\code{sys.modules}), and creates the fundamental
2229-
modules \module{__builtin__}, \module{__main__} and \module{sys}. It
2230-
also initializes the module search path (\code{sys.path}). It does
2231-
not set \code{sys.argv}; use \cfunction{PySys_SetArgv()} for that.
2232-
This is a no-op when called for a second time (without calling
2232+
modules \module{__builtin__}\refbimodindex{__builtin__},
2233+
\module{__main__}\refbimodindex{__main__} and
2234+
\module{sys}\refbimodindex{sys}. It also initializes the module
2235+
search path (\code{sys.path}).%
2236+
\indexiii{module}{search}{path}
2237+
It does not set \code{sys.argv}; use \cfunction{PySys_SetArgv()} for
2238+
that. This is a no-op when called for a second time (without calling
22332239
\cfunction{Py_Finalize()} first). There is no return value; it is a
22342240
fatal error if the initialization fails.
22352241
\end{cfuncdesc}
@@ -2277,15 +2283,17 @@ \chapter{Initialization, Finalization, and Threads}
22772283
22782284
\begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
22792285
\strong{(NEW in 1.5a3!)}
2280-
Create a new sub-interpreter. This is an (almost) totally separate
2281-
environment for the execution of Python code. In particular, the new
2282-
interpreter has separate, independent versions of all imported
2283-
modules, including the fundamental modules \module{__builtin__},
2284-
\module{__main__} and \module{sys}. The table of loaded modules
2285-
(\code{sys.modules}) and the module search path (\code{sys.path}) are
2286-
also separate. The new environment has no \code{sys.argv} variable.
2287-
It has new standard I/O stream file objects \code{sys.stdin},
2288-
\code{sys.stdout} and \code{sys.stderr} (however these refer to the
2286+
Create a new sub-interpreter. This is an (almost) totally separate
2287+
environment for the execution of Python code. In particular, the new
2288+
interpreter has separate, independent versions of all imported
2289+
modules, including the fundamental modules
2290+
\module{__builtin__}\refbimodindex{__builtin__},
2291+
\module{__main__}\refbimodindex{__main__} and
2292+
\module{sys}\refbimodindex{sys}. The table of loaded modules
2293+
(\code{sys.modules}) and the module search path (\code{sys.path}) are
2294+
also separate. The new environment has no \code{sys.argv} variable.
2295+
It has new standard I/O stream file objects \code{sys.stdin},
2296+
\code{sys.stdout} and \code{sys.stderr} (however these refer to the
22892297
same underlying \code{FILE} structures in the \C{} library).
22902298
22912299
The return value points to the first thread state created in the new
@@ -2423,6 +2431,7 @@ \chapter{Initialization, Finalization, and Threads}
24232431
\end{cfuncdesc}
24242432
24252433
\begin{cfuncdesc}{char *}{Py_GetPath}{}
2434+
\indexiii{module}{search}{path}
24262435
Return the default module search path; this is computed from the
24272436
program name (set by \cfunction{Py_SetProgramName()} above) and some
24282437
environment variables. The returned string consists of a series of
@@ -2672,11 +2681,12 @@ \section{Thread State and the Global Interpreter Lock}
26722681
lock is not created initially. This situation is equivalent to having
26732682
acquired the lock: when there is only a single thread, all object
26742683
accesses are safe. Therefore, when this function initializes the
2675-
lock, it also acquires it. Before the Python \module{thread} module
2676-
creates a new thread, knowing that either it has the lock or the lock
2677-
hasn't been created yet, it calls \cfunction{PyEval_InitThreads()}.
2678-
When this call returns, it is guaranteed that the lock has been
2679-
created and that it has acquired it.
2684+
lock, it also acquires it. Before the Python
2685+
\module{thread}\refbimodindex{thread} module creates a new thread,
2686+
knowing that either it has the lock or the lock hasn't been created
2687+
yet, it calls \cfunction{PyEval_InitThreads()}. When this call
2688+
returns, it is guaranteed that the lock has been created and that it
2689+
has acquired it.
26802690
26812691
It is \strong{not} safe to call this function when it is unknown which
26822692
thread (if any) currently has the global interpreter lock.

0 commit comments

Comments
 (0)