Embedding Python into .NET
==========================

.. warning::
    Because Python code running under Python.NET is inherently
    unverifiable, it runs totally under the radar of the security
    infrastructure of the CLR so you should restrict use of the Python
    assembly to trusted code.

The Python runtime assembly defines a number of public classes that
provide a subset of the functionality provided by the Python C-API.

These classes include PyObject, PyList, PyDict, PyTuple, etc.

At a very high level, to embed Python in your application one will need
to:

-  Reference ``Python.Runtime.dll`` (e.g. via a ``PackageReference``)
-  Call ``PythonEngine.Initialize()`` to initialize Python
-  Call ``var mod = PyModule.Import(name)`` to import a module as ``mod``

The module you import can either start working with your managed app
environment at the time its imported, or you can explicitly lookup and
call objects in a module you import.

For general-purpose information on embedding Python in applications, use
www.python.org or Google to find (C) examples. Because Python.NET is so
closely integrated with the managed environment, one will generally be
better off importing a module and deferring to Python code as early as
possible rather than writing a lot of managed embedding code.

.. note::
    Python is not free-threaded and uses a
    global interpreter lock to allow multi-threaded applications to interact
    safely with the Python interpreter. Much more information about this is
    available in the Python C-API documentation on the www.python.org
    Website.

When embedding Python in a managed application, one has to manage the
GIL in just the same way you would when embedding Python in a C or C++
application.

Before interacting with any of the objects or APIs provided by the
``Python.Runtime`` namespace, calling code must have acquired the Python
global interpreter lock by ``using'' ``Py.GIL()``. The only exception to
this rule is the ``PythonEngine.Initialize`` method, which may be called
at startup without having acquired the GIL. The GIL is released again
by disposing the return value of `Py.GIL()`:

.. code:: csharp

   using (Py.GIL())
   {
       PythonEngine.Exec("doStuff()");
   }
   
   // or
   {
       using var _ = Py.GIL()
       PythonEngine.Exec("doStuff()");
   }
   
   // or
   var gil = Py.GIL();
   try
   {
       PythonEngine.Exec("doStuff()");
   }
   finally
   {
       gil.Dispose();
   }

The ``Py.GIL()'' object is a thin wrapper over the unmanaged
``PyGILState_Ensure`` (on construction) and ``PyGILState_Release`` (on
disposal) functions from the Python API, and the documentation for those
APIs applies to the managed versions.

Passing C# Objects to the Python Engine
---------------------------------------

This section demonstrates how to pass a C# object to the Python runtime.
The example uses the following ``Person`` class:

.. code:: csharp

   public class Person
   {
       public Person(string firstName, string lastName)
       {
           FirstName = firstName;
           LastName = lastName;
       }

       public string FirstName { get; set; }
       public string LastName { get; set; }
   }

In order to pass a C# object to the Python runtime, it must be converted
to a ``PyObject``. This is done using the ``ToPython()`` extension
method. The ``PyObject`` may then be set as a variable in a ``PyScope``.
Code executed from the scope will have access to the variable:

.. code:: csharp

   // create a person object
   Person person = new Person("John", "Smith");

   // acquire the GIL before using the Python interpreter
   using (Py.GIL())
   {
       // create a Python scope
       using (PyModule scope = Py.CreateScope())
       {
           // convert the Person object to a PyObject
           PyObject pyPerson = person.ToPython();

           // create a Python variable "person"
           scope.Set("person", pyPerson);

           // the person object may now be used in Python
           string code = "fullName = person.FirstName + ' ' + person.LastName";
           scope.Exec(code);
       }
   }