openassetio::v1::python::converter Namespace Reference

Converter functionality for going between C++ and CPython objects. More...

Functions
template<typename T >
PyObject *	castToPyObject (const T &objectPtr)
	Casts a C++ API object to the equivalent Python object. More...
template<typename T >
T::Ptr	castFromPyObject (PyObject *pyObject)
	Casts a Python object to the equivalent C++ API object. More...

Detailed Description

Converter functionality for going between C++ and CPython objects.

Function Documentation

T::Ptr openassetio::v1::python::converter::castFromPyObject

(

PyObject *

pyObject

)

Casts a Python object to the equivalent C++ API object.

This template is explicitly instantiated to only the OpenAssetIO types, and is not intended to be a generic converter.

The purpose of this function is to provide a Python/C++ conversion without requiring/exposing a particular CPython binding library implementation.

The returned shared_ptr owns a hidden reference to the input PyObject, ensuring it is kept alive. The reference will be released when the shared_ptr is destroyed.

Using this function requires specifying the template argument of the C++ API type equivalent to the type of the object referred to by the pyObject pointer.

ManagerPtr manager = castFromPyObject<Manager>(pyManager);

If the types of the template argument and the pyObject are not equivalent, an exception will be thrown due to inability to perform the cast.

Note

This function does not acquire the GIL.

Warning

A Python environment, with openassetio imported, must be available in order to use this function.

Parameters

pyObject

A PyObject pointer to a Python object that must be of equivalent type to the template argument.

Returns

An OpenAssetIO pointer to a C++ API object cast from the provided pyObject. The lifetime of the PyObject will be extended to at least the lifetime of the returned shared_ptr.

Exceptions

errors.InputValidationException

if the function fails due to inability to cast between types, or if the input is null.

PyObject* openassetio::v1::python::converter::castToPyObject

(

const T &

objectPtr

)

Casts a C++ API object to the equivalent Python object.

This template is explicitly instantiated to only the OpenAssetIO types, and is not intended to be a generic converter.

The purpose of this function is to provide a Python/C++ conversion without requiring/exposing a particular CPython binding library implementation.

The returned PyObject owns a hidden reference to the input shared_ptr, ensuring it is kept alive. The reference will be released when the PyObject is destroyed.

Note

This function does not acquire the GIL.

Warning

A Python environment, with openassetio imported, must be available in order to use this function.

Parameters

objectPtr

A non-const OpenAssetIO pointer type, (e.g. ManagerPtr). The returned PyObject takes shared ownership of this input objectPtr, and will keep the C++ instance alive until the PyObject is destroyed. This parameter must be the non-const OpenAssetIO pointer type as casting to python erases constness.

Returns

A PyObject pointer to an object of the Python API type associated with the C++ API object provided. The reference count of the PyObject will be incremented, and must be decremented by the caller when done.

Exceptions

errors.InputValidationException

if the cast fails.