.. _codecs:

Codecs

Python.NET performs some conversions between .NET and Python automatically. For example, when Python calls this C# method:

.. code:: csharp

void Foo(int bar) { ... }

via Foo(42), Python value 42 of type int will be automatically converted to .NET type System.Int32. Another way to invoke those conversions is to call dotNetObject.ToPython() (available as an extension method) or pyObject.As<T>() to convert PyObject to .NET.

An incomplete list of Python types, that are converted between Python and .NET automatically: most numeric types, bool, string, Nullable<T> to its Value or None and back, etc.

A custom conversion (Codec) can be defined by implementing one of the (or both) interfaces:

• Python.Runtime.IPyObjectDecoder to marshal Python objects to .NET

.. code:: csharp

interface IPyObjectDecoder { bool CanDecode(PyObject objectType, System.Type targetType); bool TryDecode<T>(PyObject pyObj, out T value); }

• Python.Runtime.IPyObjectEncoder to marshal .NET objects to Python

.. code:: csharp

interface IPyObjectEncoder { bool CanEncode(System.Type); PyObject TryEncode(System.Object); }

Once implemented, instances have to be registered with Python.Runtime.PyObjectConversions.RegisterEncoder/-Decoder. One can override some of the default conversions by registering new codecs.

Codec priorities

When multiple codecs are registered, the runtime will first try the ones, that
were registered earlier. If you need to have some grouping of codecs by
priority, create and expose
``Python.Runtime.Codecs.EncoderGroup``/``-.DecoderGroup``. For example:

.. code:: csharp

   public static EncoderGroup HighPriorityEncoders{ get; } = new EncoderGroup();

   void Init() {
     PyObjectConversions.RegisterEncoder(HighPriorityEncoders);
     var lowPriorityEncoder = new SomeEncoder();
     PyObjectConversions.RegisterEncoder(lowPriorityEncoder);
   }

   ... some time later

   HighPriorityEncoders.Add(new SomeOtherEncoder());