<commit_before>\chapter{Embedding Python in Another Application
     \label{embedding}}

The previous chapters discussed how to extend Python, that is, how to
extend the functionality of Python by attaching a library of C
functions to it.  It is also possible to do it the other way around:
enrich your C/\Cpp{} application by embedding Python in it.  Embedding
provides your application with the ability to implement some of the
functionality of your application in Python rather than C or \Cpp.
This can be used for many purposes; one example would be to allow
users to tailor the application to their needs by writing some scripts
in Python.  You can also use it yourself if some of the functionality
can be written in Python more easily.

Embedding Python is similar to extending it, but not quite.  The
difference is that when you extend Python, the main program of the
application is still the Python interpreter, while if you embed
Python, the main program may have nothing to do with Python ---
instead, some parts of the application occasionally call the Python
interpreter to run some Python code.

So if you are embedding Python, you are providing your own main
program.  One of the things this main program has to do is initialize
the Python interpreter.  At the very least, you have to call the
function \cfunction{Py_Initialize()} (on Mac OS, call
\cfunction{PyMac_Initialize()} instead).  There are optional calls to
pass command line arguments to Python.  Then later you can call the
interpreter from any part of the application.

There are several different ways to call the interpreter: you can pass
a string containing Python statements to
\cfunction{PyRun_SimpleString()}, or you can pass a stdio file pointer
and a file name (for identification in error messages only) to
\cfunction{PyRun_SimpleFile()}.  You can also call the lower-level
operations described in the previous chapters to construct and use
Python objects.

A simple demo of embedding Python can be found in the directory
\file{Demo/embed/} of the source distribution.


\begin{seealso}
  \seetitle[../api/api.html]{Python/C API Reference Manual}{The
            details of Python's C interface are given in this manual.
            A great deal of necessary information can be found here.}
\end{seealso}


\section{Very High Level Embedding
         \label{high-level-embedding}}

The simplest form of embedding Python is the use of the very
high level interface. This interface is intended to execute a
Python script without needing to interact with the application
directly. This can for example be used to perform some operation
on a file.

\begin{verbatim}
#include <Python.h>

int main()
{
  Py_Initialize();
  PyRun_SimpleString("from time import time,ctime\n"
                     "print 'Today is',ctime(time())\n");
  Py_Finalize();
  return 0;
}
\end{verbatim}

The above code first initializes the Python interpreter with
\cfunction{Py_Initialize()}, followed by the execution of a hard-coded
Python script that print the date and time.  Afterwards, the
\cfunction{Py_Finalize()} call shuts the interpreter down, followed by<commit_msg>Use the standard argument convention for main(), and conform to the Python/C style guide.<commit_after>\chapter{Embedding Python in Another Application
     \label{embedding}}

The previous chapters discussed how to extend Python, that is, how to
extend the functionality of Python by attaching a library of C
functions to it.  It is also possible to do it the other way around:
enrich your C/\Cpp{} application by embedding Python in it.  Embedding
provides your application with the ability to implement some of the
functionality of your application in Python rather than C or \Cpp.
This can be used for many purposes; one example would be to allow
users to tailor the application to their needs by writing some scripts
in Python.  You can also use it yourself if some of the functionality
can be written in Python more easily.

Embedding Python is similar to extending it, but not quite.  The
difference is that when you extend Python, the main program of the
application is still the Python interpreter, while if you embed
Python, the main program may have nothing to do with Python ---
instead, some parts of the application occasionally call the Python
interpreter to run some Python code.

So if you are embedding Python, you are providing your own main
program.  One of the things this main program has to do is initialize
the Python interpreter.  At the very least, you have to call the
function \cfunction{Py_Initialize()} (on Mac OS, call
\cfunction{PyMac_Initialize()} instead).  There are optional calls to
pass command line arguments to Python.  Then later you can call the
interpreter from any part of the application.

There are several different ways to call the interpreter: you can pass
a string containing Python statements to
\cfunction{PyRun_SimpleString()}, or you can pass a stdio file pointer
and a file name (for identification in error messages only) to
\cfunction{PyRun_SimpleFile()}.  You can also call the lower-level
operations described in the previous chapters to construct and use
Python objects.

A simple demo of embedding Python can be found in the directory
\file{Demo/embed/} of the source distribution.


\begin{seealso}
  \seetitle[../api/api.html]{Python/C API Reference Manual}{The
            details of Python's C interface are given in this manual.
            A great deal of necessary information can be found here.}
\end{seealso}


\section{Very High Level Embedding
         \label{high-level-embedding}}

The simplest form of embedding Python is the use of the very
high level interface. This interface is intended to execute a
Python script without needing to interact with the application
directly. This can for example be used to perform some operation
on a file.

\begin{verbatim}
#include <Python.h>

int
main(int argc, char *argv[])
{
  Py_Initialize();
  PyRun_SimpleString("from time import time,ctime\n"
                     "print 'Today is',ctime(time())\n");
  Py_Finalize();
  return 0;
}
\end{verbatim}

The above code first initializes the Python interpreter with
\cfunction{Py_Initialize()}, followed by the execution of a hard-coded
Python script that print the date and time.  Afterwards, the
\cfunction{Py_Finalize()} call shuts the interpreter down, followed by
{'fraction_non_alphanumeric': 0.05230914231856739, 'fraction_numerical': 0.00031416902293433867, 'mean_word_length': 4.197551020408163, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '472214', 'n_tokens_mistral': 1617, 'n_tokens_neox': 1576, 'n_words': 917}