export_traits.h

Go to the documentation of this file.

/** @file
 *  @author Bram de Greve (bram@cocamware.com)
 *  @author Tom De Muer (tom@cocamware.com)
 *
 *  *** BEGIN LICENSE INFORMATION ***
 *  
 *  The contents of this file are subject to the Common Public Attribution License 
 *  Version 1.0 (the "License"); you may not use this file except in compliance with 
 *  the License. You may obtain a copy of the License at 
 *  http://lass.sourceforge.net/cpal-license. The License is based on the 
 *  Mozilla Public License Version 1.1 but Sections 14 and 15 have been added to cover 
 *  use of software over a computer network and provide for limited attribution for 
 *  the Original Developer. In addition, Exhibit A has been modified to be consistent 
 *  with Exhibit B.
 *  
 *  Software distributed under the License is distributed on an "AS IS" basis, WITHOUT 
 *  WARRANTY OF ANY KIND, either express or implied. See the License for the specific 
 *  language governing rights and limitations under the License.
 *  
 *  The Original Code is LASS - Library of Assembled Shared Sources.
 *  
 *  The Initial Developer of the Original Code is Bram de Greve and Tom De Muer.
 *  The Original Developer is the Initial Developer.
 *  
 *  All portions of the code written by the Initial Developer are:
 *  Copyright (C) 2004-2025 the Initial Developer.
 *  All Rights Reserved.
 *  
 *  Contributor(s):
 *
 *  Alternatively, the contents of this file may be used under the terms of the 
 *  GNU General Public License Version 2 or later (the GPL), in which case the 
 *  provisions of GPL are applicable instead of those above.  If you wish to allow use
 *  of your version of this file only under the terms of the GPL and not to allow 
 *  others to use your version of this file under the CPAL, indicate your decision by 
 *  deleting the provisions above and replace them with the notice and other 
 *  provisions required by the GPL License. If you do not delete the provisions above,
 *  a recipient may use your version of this file under either the CPAL or the GPL.
 *  
 *  *** END LICENSE INFORMATION ***
 */
 
#ifndef LASS_GUARDIAN_OF_INCLUSION_PYTHON_EXPORT_TRAITS_H
#define LASS_GUARDIAN_OF_INCLUSION_PYTHON_EXPORT_TRAITS_H
 
#include "python_common.h"
#include "shadowee_traits.h"
#include "exception.h"
#include "pyobject_ptr.h"
#include "no_none.h"
#include "maybe_none.h"
#include "self.h"
#include "../num/num_cast.h"
 
namespace lass
{
namespace python
{
 
/** @defgroup PyExportTraits
 *  @ingroup Python
 *  @brief Traits to convert between C++ and Python types
 * 
 *  `PyExportTraits<T>` is a central part of the Lass Python binding system.
 *  It defines how to convert between a C++ type `T` and a corresponding Python object.
 *  It also provides type hinting information for Python type annotations.
 * 
 *  Client code will not usually use these traits directly, but rather use the functions
 *  `pyBuildSimpleObject()` and `pyGetSimpleObject()`:
 * 
 *  ```
 *  TPyObjPtr pyObj( pyBuildSimpleObject(cppValue) );
 *  if (!pyObj)
 *    // error occurred, Python exception set
 *  
 *  T cppValue2;
 *  if (pyGetSimpleObject(pyObj.get(), cppValue2) != 0)
 *    // error occurred, Python exception set
 *  ```
 * 
 *  A well-defined `PyExportTraits<T>` specialization provides the following parts,
 *  all of which are optional:
 *  
 *  - Python type hinting information: `py_typing`, `py_typing_param`, `py_typing_preamble`
 *  - A static method `build(const T& value)` that converts a C++ value to a new Python object.
 *  - A static method `get(PyObject* obj, T& value)` that converts a Python object to a C++ value.
 * 
 *  ```
 *  template <typename T>
 *  struct PyExportTraits<Spam<T>>
 *  {
 *      constexpr static const char* py_typing = "Spam[T]";
 *      constexpr static const char* py_typing_param = "_Spam[T]";
 *      constexpr static const char* py_typing_preamble = "type _Spam[T] = Spam[T] | T";
 *
 *      static PyObject* build(const Spam<T> &value)
 *      {
 *          // Construct PyObject from value and return new reference.
 *          // Or set Python error and return nullptr on failure.
 *      }
 *      static int get(PyObject* obj, Spam<T>& value)
 *      {
 *          // Extract and set value from obj, and return 0 on success.
 *          // Or set Python error and return -1 on failure.
 *      }
 *  }
 *  ```
 *
 *
 *
 *  ### Building Python objects from C++ values
 * 
 *  The `build()` method should return a new reference to a Python object that represents the C++
 *  value passed as argument. If the conversion fails, it should set a Python exception and
 *  return nullptr. 
 * 
 *  Its return type must be `PyObject*`, and it must accept a single argument of type `const T&`.
 * 
 *  If a `PyExportTraits<T>` specialization does not provide a `build()` method, then the C++
 *  type cannot be converted to Python. This is only useful for types that can only be used as
 *  function parameters, but not as return values or attributes.
 * 
 *  Client code will usually not call the `build()` method directly, but rather use the
 *  `pyBuildSimpleObject()` function, which will call the `build()` method internally.
 *
 *
 *
 *  ### Getting C++ values from Python objects
 * 
 *  The `get()` method should extract the C++ value from the Python object passed as argument,
 *  and store it in the second argument passed by reference. If the conversion is successful,
 *  it should return 0. If the conversion fails, it should set a Python exception and return 1.
 * 
 *  The first argument must be of type `PyObject*`, and the `get()` shall _not_ eat a reference.
 *  In other words, the `get()` method gets a borrowed reference to the Python object.
 * 
 *  The second argument must be of type `T&`, and the `get()` method should set this value if
 *  conversion is successful.
 * 
 *  @note Some types cannot define a meaningful `get()` method, such as types that cannot be
 *  default-constructed, or types that don't have a well-defined lifetime, such as `char*` strings.
 *  In such cases, the `PyExportTraits<T>` specialization should not provide a `get()` method.
 *  But that does not mean that these types cannot be used as function parameters. By specializing
 *  `ArgumentTraits` for these types, you can still support them as function parameters, and it may
 *  still make sense to define `py_typing_param` for type hinting. See `ArgumentTraits` for more
 *  details on techniques to support such types as function parameters.
 *
 *
 * 
 *  ### Type Hinting
 * 
 *  The three type hinting members are used in combination with lass_stubgen to automatically 
 *  generate Python stub files (.pyi) that provide type hinting information for Python extension
 *  modules that use the Lass binding system.
 * 
 *  All three members are of type `constexpr static const char*`, and are optional:
 * 
 *  - `py_typing`: the type in Python typing syntax.
 *  - `py_typing_param`: the Python type when used as a function parameter.
 *  - `py_typing_preamble`: additional Python code that needs to be included to support the type
 *                          hinting, such as type aliases or imports.
 *
 *
 *  #### `py_typing`
 * 
 *  To generate useful type hints, you need to provide at least the `py_typing` member. This should
 *  be a string that describes the type in Python typing syntax. For example, for the C++ type 
 *  `prim::ColorRGBA` will always convert to a tuple of 4 floats `(r, g, b, a)`, and can be
 *  described as:
 *  ```
 *  template <>
 *  struct PyExportTraits<prim::ColorRGBA>
 *  {
 *      constexpr static const char* py_typing = "tuple[float, float, float, float]";
 *  };
 *  ```
 *
 * 
 *  #### `py_typing_param`
 * 
 *  When `py_typing_param` is provided, it will be used instead of `py_typing` when the type is used
 *  as a function parameter. This is useful for types that can be converted from additional types
 *  when used as a parameter. For example, `prim::ColorRGBA` will always convert to a tuple of 4
 *  floats `(r, g, b, a)` when returned from a function, but it will also accept `(r, g, b), a tuple
 *  of 3 floats without the alpha channel `(r, g, b)` as argument:
 *  ```
 *  template <>
 *  struct PyExportTraits<prim::ColorRGBA>
 *  {
 *      constexpr static const char* py_typing = "tuple[float, float, float, float]";
 *      constexpr static const char* py_typing_param = "tuple[float, float, float, float] | tuple[float, float, float]";
 *  };
 *  ```
 *
 *
 *  #### `py_typing_preamble`
 * 
 *  `py_typing_preamble` can be used to provide additional Python code that needs to be added to the
 *  generated stub files to support the type hinting. This can be used to define type aliases to
 *  make the type hints more readable. For example, for `prim::ColorRGBA`, we define two aliases
 *  `_RGBA` and `_RGB` to make the type hints more readable. The preamble can consist of multiple
 *  lines, separated by newline characters. Each type alias will be of the form `type _Name = ...`:
 *  ```
 *  template <>
 *  struct PyExportTraits<prim::ColorRGBA>
 *  {
 *      constexpr static const char* py_typing = "_RGBA";
 *      constexpr static const char* py_typing_param = "_RGBA | _RGB";
 *      constexpr static const char* py_typing_preamble =
 *          "type _RGBA = tuple[float, float, float, float]\n"
 *          "type _RGB = tuple[float, float, float]";
 *  };
 *  ```
 *
 *  The preamble can also be used to include necessary imports. For example, `std::filesystem::path`
 *  is mapped to `pathlib.Path` in Python, so the `pathlib` module needs to be imported. And as 
 *  parameter, it also accepts `str` and `bytes`, or anything that implements the `os.PathLike`
 *  for which the `StrOrBytesPath` type alias from the `_typeshed` module is used:
 * 
 *  ```
 *  template <>
 *  struct PyExportTraits<std::filesystem::path>
 *  {
 *      constexpr static const char* py_typing = "pathlib.Path";
 *      constexpr static const char* py_typing_param = "StrOrBytesPath";
 *      constexpr static const char* py_typing_preamble = "import pathlib\nfrom _typeshed import StrOrBytesPath";
 *  };
 *  ```
 * 
 *  @note Type-aliases should start with an underscore to indicate they are private and not really
 *        part of the module API. They only exist for the purpose of type hinting and checking.
 *        Attempting to import them at runtime will result in a failure, unless you hide the code
 *        in a `if TYPE_CHECKING:` block.
 *        See https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING
 *
 *  @note It is also *your* responsibility to ensure that the type aliases do not conflict with any
 *        other names in the module or in the Python standard library.
 *
 *  @note The preamble can only contain type aliases and imports.
 *
 *
 *  #### Partial Specializations
 *
 *  If a `PyExportTraits` is partially specialized, such as for template classes, then the
 *  template parameters can be used in the `py_typing` and `py_typing_param` members. They will be
 *  substituted with the corresponding Python type hints of the template parameters. For example:
 *  for the C++ type `std::pair<T, U>` translates to a Python tuple of two elements, and is
 *  described as:
 *  ```
 *  template <typename T, typename U>
 *  struct PyExportTraits<std::pair<T, U>>
 *  {
 *      constexpr static const char* py_typing = "tuple[T, U]";
 *  };
 *  ```
 * 
 *  When substituing template parameters in the context of function parameters, then
 *  `py_typing_param` is used if the template argument defines it, even if the top-level
 *  `PyExportTraits` specialization only defines `py_typing`. For example, `std::pair<T, U>` only
 *  defines `py_typing`, but `float` defines the alias `_Float` as `py_typing_param`. So a
 *  function taking `std::pair<float, float>` as a parameter would have the following type hint:
 *  ```
 *  def func(param: tuple[_Float, _Float]) -> None:
 *      ...
 *  ```
 * 
 *  But sometimes, you really want to substitute the template parameters by their `py_typing` type,
 *  even in the context of function parameters. In that case, you can add an exlamation mark `!`
 *  after the template parameter name as special syntax to indicate that you always want to replace
 *  it by its `py_typing` type.
 * 
 *  One example where this is useful is callable types, such as `std::function<R(T, U)>`. What
 *  you're really saying when a function takes a `std::function<R(T, U)>` as parameter, is that
 *  it takes a callable that accepts two parameters of type `T` and `U`, and that you will call
 *  that callable from C++, you are providing the arguments of type `T` and `U` from C++ to Python,
 *  similar like returning values from a normal function. So in this case, you want the types of
 *  the T and U arguments to be substituted by their `py_typing` type, not their `py_typing_param`
 *  type. So you would define the `PyExportTraits` specialization as:
 *  ```
 *  template <typename R, typename T, typename U>
 *  struct PyExportTraits<std::function<R(T, U)>>
 *  {
 *      constexpr static const char* py_typing = "Callable[[T!, U!], R!]";
 *  };
 *  ```
 */
 
 
namespace impl
{
    template <typename T> struct ShadowTraits;
 
    template <typename In, typename Out>
    [[deprecated]] int pyNumCast(In in, Out& out)
    {
        try
        {
            out = num::numCast<Out>(in);
        }
        catch (const std::exception& error)
        {
            PyErr_SetString(PyExc_TypeError, error.what());
            return 1;
        }
        return 0;
    }
 
    template <typename T>
    using NoNone [[deprecated("lass::python::NoNone<T> instead.")]] = lass::python::NoNone<T>;
 
    LASS_PYTHON_DLL PyObject* buildStringImpl(const char* s, size_t n);
    LASS_PYTHON_DLL PyObject* buildStringImpl(const wchar_t* s, size_t n);
#if LASS_HAVE_STD_U8STRING
#if __cpp_lib_char8_t
    LASS_PYTHON_DLL PyObject* buildStringImpl(const char8_t* s, size_t n);
#endif
#endif
    LASS_PYTHON_DLL PyObject* buildStringImpl(const char16_t* s, size_t n);
    LASS_PYTHON_DLL PyObject* buildStringImpl(const char32_t* s, size_t n);
}
 
/** by copy, general case assumes shadow type or PyObjectPlus based type.
 *  @ingroup PyExportTraits
 */
template <typename T> 
struct PyExportTraits
{
    typedef impl::ShadowTraits<typename ShadoweeTraits<T>::TShadow> TShadowTraits; 
    static PyObject* build(const T& v)
    {
        return fromSharedPtrToNakedCast(TShadowTraits::buildObject(v));
    }
    static int get(PyObject* obj, T& v)
    {
        return TShadowTraits::getObject(obj, v);
    }
};
 
/** constant objects can only be build.
 *  @ingroup PyExportTraits
 */
template <typename T>
struct PyExportTraits<const T>
{
    static PyObject* build(const T& v)
    {
        return PyExportTraits<T>::build(v);
    }
};
 
 
// --- pointers ------------------------------------------------------------------------------------
 
/** @ingroup PyExportTraits
 */
template <typename T>
struct PyExportTraits< T* >
{
    typedef impl::ShadowTraits<typename ShadoweeTraits<T>::TShadow> TShadowTraits; 
    static PyObject* build(T* value)
    {
        if (!value)
        {
            Py_RETURN_NONE;
        }
        return fromSharedPtrToNakedCast(TShadowTraits::buildObject(value));
    }
    static int get(PyObject* obj, T*& value)
    {
        if (obj == Py_None)
        {
            value = 0;
            return 0;
        }
        return TShadowTraits::getObject(obj, value);
    }
};
 
/** SharedPtr assumes shadow types or PyObjectPlus types.
 * 
 *  If it's a nullptr, it is mapped to `None`.
 *  Otherwise, it is mapped to the actual Python object, increasing the reference count.
 * 
 *  When getting a SharedPtr from Python, `None` is mapped to a nullptr.
 *  Otherwise it has to be of the correct type, and the SharedPtr will share ownership of the object.
 *
 *  @ingroup PyExportTraits
 */
template <typename T, template <typename, typename> class S, typename C>
struct PyExportTraits< util::SharedPtr<T, S, C> >
{
    constexpr static const char* py_typing = "T | None";
 
    typedef impl::ShadowTraits<typename ShadoweeTraits<T>::TShadow> TShadowTraits; 
    typedef util::SharedPtr<T, S, C> TPtr;
    static PyObject* build(const TPtr& value)
    {
        if (!value)
        {
            Py_RETURN_NONE;
        }
        return fromSharedPtrToNakedCast(TShadowTraits::buildObject(value));
    }
    static int get(PyObject* obj, TPtr& value)
    {
        if (obj == Py_None)
        {
            value = TPtr();
            return 0;
        }
        return TShadowTraits::getObject(obj, value);
    }
};
 
 
/** A shared `PyObject` pointer is mapped to `Any` in Python.
 * 
 *  If it's a nullptr, it is mapped to `None`.
 *  Otherwise, it is mapped to the actual Python object, increasing the reference count.
 * 
 *  When getting a `PyObject` pointer from Python, `None` is mapped to a nullptr,
 *  so you can never get `Py_None` as a TPyObjPtr value.
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<TPyObjPtr>
{
    constexpr static const char* py_typing = "Any";
 
    static PyObject* build(const TPyObjPtr& v)
    {
        if (!v)
        {
            Py_RETURN_NONE;
        }
        return fromSharedPtrToNakedCast(v);
    }
    static int get(PyObject* obj, TPyObjPtr& v)
    {
        if (obj == Py_None)
        {
            v = TPyObjPtr();
        }
        v = fromNakedToSharedPtrCast<PyObject>(obj);
        return 0;
    }
};
 
 
/** @ingroup PyExportTraits
 */
/*
template <typename T>
struct PyExportTraits< util::SharedPtr<T, PyObjectStorage, PyObjectCounter> >
{
    static PyObject* build( const util::SharedPtr<T, PyObjectStorage, PyObjectCounter>& iV )
    {
        if (!iV)
        {
            Py_RETURN_NONE;
        }
        return fromSharedPtrToNakedCast(iV);
    }
    static int get(PyObject* iValue, util::SharedPtr<T, PyObjectStorage, PyObjectCounter>& oV)
    {
        const bool isNone = (iValue == Py_None );
        if (isNone)
        {
            oV = util::SharedPtr<T, PyObjectStorage, PyObjectCounter>();
        }
        else
        {
            if (!PyType_IsSubtype(iValue->ob_type , T::_lassPyClassDef.type() ))
            {
                PyErr_Format(PyExc_TypeError,"not castable to %s",T::_lassPyClassDef.name() );
                return 1;
            }
            oV = fromNakedToSharedPtrCast<T>(iValue);
        }
        return 0;
    }
};
*/
 
 
/** std::unique_ptr assumes shadow types
*  @ingroup PyExportTraits
*/
template <typename T, typename Deleter>
struct PyExportTraits< std::unique_ptr<T, Deleter> >
{
    constexpr static const char* py_typing = "T | None";
 
    typedef impl::ShadowTraits<typename ShadoweeTraits<T>::TShadow> TShadowTraits;
    static PyObject* build(std::unique_ptr<T, Deleter>&& value)
    {
        if (!value)
        {
            Py_RETURN_NONE;
        }
        return fromSharedPtrToNakedCast(TShadowTraits::buildObject(std::move(value)));
    }
};
 
 
/** std::shared_ptr assumes shadow types.
 *  @ingroup PyExportTraits
 */
template <typename T>
struct PyExportTraits< std::shared_ptr<T> >
{
    constexpr static const char* py_typing = "T | None";
 
    typedef impl::ShadowTraits<typename ShadoweeTraits<T>::TShadow> TShadowTraits;
    typedef std::shared_ptr<T> TPtr;
    static PyObject* build(const TPtr& value)
    {
        if (!value)
        {
            Py_RETURN_NONE;
        }
        return fromSharedPtrToNakedCast(TShadowTraits::buildObject(value));
    }
    static int get(PyObject* obj, TPtr& value)
    {
        if (obj == Py_None)
        {
            value.reset();
            return 0;
        }
        return TShadowTraits::getObject(obj, value);
    }
};
 
// --- void ptrs ------------------------------------------------------------------------------------
 
/** @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<void*>
{
    constexpr static const char* py_typing = "Any"; // should be CapsuleType | None instead?
 
    LASS_PYTHON_DLL static PyObject* build(void* value);
    LASS_PYTHON_DLL static int get(PyObject* obj, void*& value);
};
 
 
 
/** @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<std::nullptr_t>
{
    constexpr static const char* py_typing = "None";
 
    LASS_PYTHON_DLL static PyObject* build(std::nullptr_t value);
    LASS_PYTHON_DLL static int get(PyObject* obj, std::nullptr_t& value);
};
 
 
 
// --- NoNone --------------------------------------------------------------------------------------
 
/** Helper class to create PyExportTraits for NoNone wrapped types.
 *
 *  NoNone wrapped types are used to ensure that:
 *  - No `None` values can be passed from Python to C++ (which would be translated to a `nullptr`),
 *  - No `nullptr` values can be returned to Python (which would be translated to a `None`).
 *
 *  Use this helper to create PyExportTraits for your own NoNone wrapped types by inheriting from it.
 *
 *  ```
 *  template <typename T, template <typename, typename> class S, typename C>
 *  struct PyExportTraits< NoNone< util::SharedPtr<T, S, C> > >: public PyExportTraitsNoNone< util::SharedPtr<T, S, C> >
 *  {
 *      constexpr static const char* py_typing = "T"; // optional
 *  };
 *  ```
 *
 *  Built-in specializations are provided for raw pointers `T*`, util::SharedPtr<T>, and `std::shared_ptr<T>`.
 *
 *  @note If you use `typename T` as the main template parameter for your actual type, then the
 *  Python type will automatically be deduced. If not, or if you still see a `T | None` type-hint,
 *  you can can override the `py_typing` member to specify the type-hint you want.
 *
 *  @ingroup PyExportTraits NoNone
 *  @sa NoNone
 *  @sa PyExportTraits<NoNone<T*>>
 *  @sa PyExportTraits<NoNone<util::SharedPtr<T,S,C>>>
 *  @sa PyExportTraits<NoNone<std::shared_ptr<T>>>
 */
template <typename T>
struct PyExportTraitsNoNone
{
    constexpr static const char* py_typing = "T";
 
    /** Raise a Python `TypeError` if @a value is equal to `nullptr` */
    static PyObject* build(const NoNone<T>& value)
    {
        const T& v = static_cast<const T&>(value);
        if (v == nullptr)
        {
            PyErr_SetString(PyExc_TypeError, "value must be not be None");
            return nullptr;
        }
        return PyExportTraits<T>::build(value);
    }
    /** Raise a Python `TypeError` if @a obj is equal to `None` */
    static int get(PyObject* obj, NoNone<T>& value)
    {
        if (obj == Py_None)
        {
            PyErr_SetString(PyExc_TypeError, "argument must be not be None");
            return 1;
        }
        return PyExportTraits<T>::get(obj, value);
    }
};
 
/** NoNone<T*> type-hints as `T` and refuses `None` as value.
 *
 *  @ingroup PyExportTraits NoNone
 *  @sa NoNone
 *  @sa PyExportTraitsNoNone
 */
template <typename T>
struct PyExportTraits< NoNone<T*> > : public PyExportTraitsNoNone<T*>
{
};
 
/** Type-hints NoNone<util::SharedPtr<T>> as `T` and refuses `None` as value.
 *
 *  @ingroup PyExportTraits NoNone
 *  @sa NoNone
 *  @sa util::SharedPtr
 *  @sa PyExportTraitsNoNone
 */
template <typename T, template <typename, typename> class S, typename C>
struct PyExportTraits< NoNone< util::SharedPtr<T, S, C> > > : public PyExportTraitsNoNone< util::SharedPtr<T, S, C> >
{
};
 
/** NoNone<std::shared_ptr<T>> type-hints as `T` and refuses `None` as value.
 *
 *  @ingroup PyExportTraits NoNone
 *  @sa NoNone
 *  @sa PyExportTraitsNoNone
 */
template <typename T>
struct PyExportTraits< NoNone< std::shared_ptr<T> > > : public PyExportTraitsNoNone< std::shared_ptr<T> >
{
};
 
 
 
// --- MaybeNone -----------------------------------------------------------------------------------
 
/** Helper class to create PyExportTraits for MaybeNone wrapped types.
 *
 *  MaybeNone does not provide any runtime or compile-time checks. It only serves to alter the
 *  type-hint to `T | MaybeNone` in Python, which is useful for type-checking, see [The Any Trick].
 * 
 *  MaybeNone<T> types can only be returned from C++ to Python, it doesn't make sense to pass them
 *  as function parameters to C++.
 *
 *  Use this helper to create PyExportTraits for your own MaybeNone wrapped types by inheriting from it.
 *
 *  ```
 *  template <typename T, template <typename, typename> class S, typename C>
 *  struct PyExportTraits< MaybeNone< util::SharedPtr<T, S, C> > >: public PyExportTraitsMaybeNone< util::SharedPtr<T, S, C> >
 *  {
 *      constexpr static const char* py_typing = "T | MaybeNone"; // optional
 *  };
 *  ```
 *
 *  Built-in specializations are provided for raw pointers `T*`, util::SharedPtr<T>, `std::shared_ptr<T>`,
 *  and `std::optional<T>`.
 *
 *  @note If you use `typename T` as the main template parameter for your actual type, then the
 *  Python type will automatically be deduced. If not, or if you still see a `T | None` type-hint,
 *  you can can override the `py_typing` member to specify the type-hint you want.
 * 
 *  [The Any Trick]: https://typing.python.org/en/latest/guides/writing_stubs.html#the-any-trick
 *
 *  @ingroup PyExportTraits
 *  @sa MaybeNone
 *  @sa PyExportTraits<MaybeNone<T*>>
 *  @sa PyExportTraits<MaybeNone<util::SharedPtr<T,S,C>>>
 *  @sa PyExportTraits<MaybeNone<std::shared_ptr<T>>>
 *  @sa PyExportTraits<MaybeNone<std::optional<T>>>
 */
template <typename T>
struct PyExportTraitsMaybeNone
{
    constexpr static const char* py_typing = "T | MaybeNone";
    constexpr static const char* py_typing_preamble = "from _typeshed import MaybeNone";
 
    static PyObject* build(const MaybeNone<T>& value)
    {
        return PyExportTraits<T>::build(value);
    }
};
 
/** MaybeNone<T*> type-hints a type as `T | MaybeNone`
 * 
 *  @ingroup PyExportTraits
 *  @sa MaybeNone
 *  @sa PyExportTraitsMaybeNone
 */
template <typename T>
struct PyExportTraits< MaybeNone<T*> > : public PyExportTraitsMaybeNone<T*>
{
};
 
/** MaybeNone<util::SharedPtr<T>> type-hints a type as `T | MaybeNone`
 * 
 *  @ingroup PyExportTraits
 *  @sa MaybeNone
 *  @sa util::SharedPtr
 *  @sa PyExportTraitsMaybeNone
 */
template <typename T, template <typename, typename> class S, typename C>
struct PyExportTraits< MaybeNone< util::SharedPtr<T, S, C> > > : public PyExportTraitsMaybeNone< util::SharedPtr<T, S, C> >
{
};
 
/** MaybeNone<std::shared_ptr<T>> type-hints a type as `T | MaybeNone`
 * 
 *  @ingroup PyExportTraits
 *  @sa MaybeNone
 *  @sa PyExportTraitsMaybeNone
 */
template <typename T>
struct PyExportTraits< MaybeNone< std::shared_ptr<T> > > : public PyExportTraitsMaybeNone< std::shared_ptr<T> >
{
};
 
 
 
// --- Self --------------------------------------------------------------------------------------
 
/** Self<T> type-hints as `Self`.
 *
 *  @ingroup PyExportTraits
 *  @sa Self
 */
template <typename T>
struct PyExportTraits< Self<T> > : public PyExportTraits<T>
{
    constexpr static const char* py_typing = "Self";
#if PY_VERSION_HEX < 0x030b0000 // < 3.11
    constexpr static const char* py_typing_preamble = "from typing_extensions import Self";
#else
    constexpr static const char* py_typing_preamble = "from typing import Self";
#endif
};
 
 
 
// --- booleans ------------------------------------------------------------------------------------
 
/** @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<bool>
{
    constexpr static const char* py_typing = "bool";
 
    LASS_PYTHON_DLL static PyObject* build(bool v);
    LASS_PYTHON_DLL static int get(PyObject* obj, bool& v);
};
 
 
// --- signed integers -----------------------------------------------------------------------------
 
/** Helper class to create PyExportTraits for signed integers
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <typename Integer>
struct PyExportTraitsSigned
{
    constexpr static const char* py_typing = "int";
 
    LASS_META_ASSERT(sizeof(Integer) <= sizeof(long), integer_should_fit_in_long);
    static PyObject* build(Integer v)
    {
        return PyLong_FromLong(v);
    }
    static int get(PyObject* obj, Integer& v)
    {
#if LASS_USE_OLD_EXPORTRAITS_INT
        if (PyLong_Check(obj))
        {
#   if HAVE_LONG_LONG
            const PY_LONG_LONG x = PyLong_AsLongLong(obj);
#   else
            const long x = PyLong_AsLong(obj);
#   endif
            if (PyErr_Occurred())
            {
                PyErr_Format(PyExc_TypeError, "not a %s: overflow", num::NumTraits<Integer>::name().c_str());
                return 1;
            }
            return impl::pyNumCast(x, v);
        }
        PyErr_SetString(PyExc_TypeError, "not an integer");
        return 1;
#else
#   if PY_VERSION_HEX < 0x030a0000 // < 3.10
        // PyLong_AsLongLong also accept __int__, so floats are ints too :-(
        // From 3.10 onwards, __int__ is no longer accepted, only __index__.
        // Let's do the same for Python < 3.10.
        if (!PyLong_Check(obj))
        {
            TPyObjPtr o(PyNumber_Index(obj));
            if (!o)
            {
                // PyErr_SetString(PyExc_TypeError, "not an integer");
                return 1;
            }
            return PyExportTraits<Integer>::get(o.get(), v);
        }
#   endif
#   if HAVE_LONG_LONG
            const PY_LONG_LONG x = PyLong_AsLongLong(obj);
#   else
            const long x = PyLong_AsLong(obj);
#   endif
        if (x == -1 && PyErr_Occurred())
        {
            return 1;
        }
        try
        {
            v = num::numCast<Integer>(x);
        }
        catch (const num::BadNumCast& err)
        {
            PyErr_SetString(PyExc_OverflowError, err.what());
            return 1;
        }
        return 0;
#endif
    }
};
 
/** `signed char` is mapped to Python `int`
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<signed char>: PyExportTraitsSigned<signed char>
{
};
 
/** `signed short` is mapped to Python `int`
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<signed short>: PyExportTraitsSigned<signed short>
{
};
 
/** `signed int` is mapped to Python `int`
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<signed int>: PyExportTraitsSigned<signed int>
{
};
 
/** `signed long` is mapped to Python `int`
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<signed long>: PyExportTraitsSigned<signed long>
{
};
 
 
 
// --- unsigned integers ---------------------------------------------------------------------------
 
/** Helper class to create PyExportTraits for unsigned integers
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <typename Integer>
struct PyExportTraitsUnsigned
{
    constexpr static const char* py_typing = "int";
 
    LASS_META_ASSERT(sizeof(Integer) <= sizeof(unsigned long), integer_should_fit_in_unsigned_long);
    static PyObject* build(Integer v)
    {
        return PyLong_FromUnsignedLong(v);
    }
    static int get(PyObject* obj, Integer& v)
    {
#if LASS_USE_OLD_EXPORTRAITS_INT
        if (PyLong_Check(obj))
        {
#   if HAVE_LONG_LONG
            const unsigned PY_LONG_LONG x = PyLong_AsUnsignedLongLong(obj);
#   else
            const unsigned long x = PyLong_AsUnsignedLong(obj);
#   endif
            if (PyErr_Occurred())
            {
                PyErr_Format(PyExc_TypeError, "not a %s: overflow", num::NumTraits<Integer>::name().c_str());
                return 1;
            }
            return impl::pyNumCast(x, v);
        }
        PyErr_SetString(PyExc_TypeError, "not an integer");
        return 1;
#else
    if (!PyLong_Check(obj))
    {
        // PyLong_AsUnsignedLongLong and PyLong_AsUnsignedLong only accepts PyLong objects.
        // They don't try to use __index__, so let's do this explicitly.
        TPyObjPtr o(PyNumber_Index(obj));
        if (!o)
        {
            // PyErr_SetString(PyExc_TypeError, "not an integer");
            return 1;
        }
        return PyExportTraits<Integer>::get(o.get(), v);
    }
#   if HAVE_LONG_LONG
        const unsigned PY_LONG_LONG x = PyLong_AsUnsignedLongLong(obj);
        if (x == ((unsigned PY_LONG_LONG) - 1) && PyErr_Occurred())
        {
            return 1;
        }
#   else
        const unsigned long x = PyLong_AsUnsignedLong(obj);
        if (x == ((unsigned long) - 1) && PyErr_Occurred())
        {
            return 1;
        }
#   endif
        try
        {
            v = num::numCast<Integer>(x);
        }
        catch (const num::BadNumCast& err)
        {
            PyErr_SetString(PyExc_OverflowError, err.what());
            return 1;
        }
        return 0;
#endif
    }
};
 
/** `unsigned char` is mapped to Python `int`
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<unsigned char>: PyExportTraitsUnsigned<unsigned char>
{
};
 
/** `unsigned short` is mapped to Python `int`
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<unsigned short>: PyExportTraitsUnsigned<unsigned short>
{
};
 
/** `unsigned int` is mapped to Python `int`
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<unsigned int>: PyExportTraitsUnsigned<unsigned int>
{
};
 
/** `unsigned long` is mapped to Python `int`
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<unsigned long>: PyExportTraitsUnsigned<unsigned long>
{
};
 
// --- long long -----------------------------------------------------------------------------------
 
#ifdef HAVE_LONG_LONG
 
/** `signed long long` is mapped to Python `int`
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<signed PY_LONG_LONG>
{
    constexpr static const char* py_typing = "int";
 
    LASS_PYTHON_DLL static PyObject* build(signed PY_LONG_LONG v);
    LASS_PYTHON_DLL static int get(PyObject* obj, signed PY_LONG_LONG& v);
};
 
/** `unsigned long long` is mapped to Python `int`
 *
 *  An `OverflowError` will be set when trying to get a value that is out of range.
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<unsigned PY_LONG_LONG>
{
    constexpr static const char* py_typing = "int";
 
    LASS_PYTHON_DLL static PyObject* build(unsigned PY_LONG_LONG v);
    LASS_PYTHON_DLL static int get(PyObject* obj, unsigned PY_LONG_LONG& v);
};
 
#endif
 
 
 
// --- floating point numbers ----------------------------------------------------------------------
 
/** Helper class to create PyExportTraits for floating point numbers
 *  @ingroup PyExportTraits
 */
template <typename Float>
struct PyExportTraitsFloat
{
    constexpr static const char* py_typing = "float";
    constexpr static const char* py_typing_param = "_Float";
    constexpr static const char* py_typing_preamble =
        "from typing import SupportsFloat, SupportsIndex\n"
        "type _Float = float | SupportsFloat | SupportsIndex\n";
 
    static PyObject* build(Float v)
    {
        return PyFloat_FromDouble(v);
    }
    static int get(PyObject* obj, Float& v)
    {
#if LASS_USE_OLD_EXPORTRAITS_FLOAT
        if (PyFloat_Check(obj))
        {
            return impl::pyNumCast(PyFloat_AS_DOUBLE(obj), v);
        }
        if (PyLong_Check(obj))
        {
            const double x = PyLong_AsDouble(obj);
            if (PyErr_Occurred())
            {
                PyErr_Format(PyExc_TypeError, "not a %s: overflow", num::NumTraits<Float>::name().c_str());
                return 1;
            }
            return impl::pyNumCast(x, v);
        }
        PyErr_SetString(PyExc_TypeError, "not a float or integer");
        return 1;
#else
        double x;
        if (PyFloat_CheckExact(obj))
        {
            x = PyFloat_AS_DOUBLE(obj);
        }
        else if (PyLong_Check(obj))
        {
            x = PyLong_AsDouble(obj);
            if (x == -1.0 && PyErr_Occurred())
            {
                return 1;
            }
        }
        else
        {
            x = PyFloat_AsDouble(obj);
            if (x == -1.0 && PyErr_Occurred())
            {
                return 1;
            }
        }
        v = static_cast<Float>(x);
        return 0;
#endif
    }
};
 
/** `float` is mapped to Python `float` type, which is a C `double`.
 *
 *  As argument, other Python types than `float` are also accepted, as long as they can be
 *  converted to a floating point number, i.e. `int`, and any type implementing the `__float__` or
 *  `__index__` methods.
 *
 *  @note This means that precision may be lost when converting from a Python `float` to a
 *        C++ `float`, similar to converting from a `double` to a `float` using a static cast:
 *        `static_cast<float>(doubleValue)`. No exception is raised in this case.
 *
 *  @sa PyExportTraitsFloat
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<float>: PyExportTraitsFloat<float>
{
};
 
/** `double` is mapped to Python `float` type, which is also a C `double`.
 *
 *  As argument, other Python types than `float` are also accepted, as long as they can be
 *  converted to a floating point number, i.e. `int`, and any type implementing the `__float__` or
 *  `__index__` methods.
 *
 * @sa PyExportTraitsFloat
 * @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<double>: PyExportTraitsFloat<double>
{
};
 
/** `long double` is mapped to Python `float` type, which is a C `double`.
 *
 *  As argument, other Python types than `float` are also accepted, as long as they can be
 *  converted to a floating point number, i.e. `int`, and any type implementing the `__float__` or
 *  `__index__` methods.
 *
 * @note This means that precision may be lost when converting from a C++ `long double` to a
 *       Python `float`, similar to converting from a `long double` to a `double` using a static
 *       cast: `static_cast<double>(longDoubleValue)`. No exception is raised in this case.
 *
 * @sa PyExportTraitsFloat
 * @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<long double>: PyExportTraitsFloat<long double>
{
};
 
 
 
// --- complex numbers -----------------------------------------------------------------------------
 
/** `std::complex<T>` is always mapped to Python `complex` type.
 *
 *  As argument, other Python types than `complex` are also accepted, as long as they can be
 *  converted to a complex number, i.e. `int`, `float`, and any type implementing the `__complex__`,
 *  `__float__`, or `__index__` methods.
 *
 *  @note The Python `complex` type uses C `double` precision for both real and imaginary parts,
 *        meaning that precision may be lost when converting to a `std::complex<float>` or from a
 *        `std::complex<long double>`, similar to using `static_cast` to convert between floating
 *        point types. No exception is raised in this case.
 *
 *  @ingroup PyExportTraits
 */
template <typename T>
struct PyExportTraits< std::complex<T> >
{
    constexpr static const char* py_typing = "complex";
    constexpr static const char* py_typing_param = "_Complex";
    constexpr static const char* py_typing_preamble = 
        "from typing import SupportsComplex, SupportsFloat, SupportsIndex\n"
        "type _Complex = complex | SupportsComplex | SupportsFloat | SupportsIndex\n";
 
    static PyObject* build(const std::complex<T>& v)
    {
        return PyComplex_FromDoubles(
            static_cast<double>(v.real()), 
            static_cast<double>(v.imag()));
    }
    static int get(PyObject* obj, std::complex<T>& v)
    {
#if LASS_USE_OLD_EXPORTRAITS_COMPLEX
        T re, im;
        if (PyExportTraits<T>::get(obj, re) == 0)
        {
            v = std::complex<T>(re, 0);
            return 0;
        }
        PyErr_Clear();
        if (!PyComplex_Check(obj))
        {
            PyErr_SetString(PyExc_TypeError, "not a complex number");
            return 1;
        }
        if (impl::pyNumCast(PyComplex_RealAsDouble(obj), re) != 0)
        {
            return 1;
        }
        if (impl::pyNumCast(PyComplex_ImagAsDouble(obj), im) != 0)
        {
            return 1;
        }
        v = std::complex<T>(re, im);
        return 0;
#else
        Py_complex c = PyComplex_AsCComplex(obj);
        if (c.real == -1.0 && PyErr_Occurred())
        {
            return 1;
        }
        v = std::complex<T>(static_cast<T>(c.real), static_cast<T>(c.imag));
        return 0;
#endif
    }
};
 
 
 
// --- strings -------------------------------------------------------------------------------------
 
/** `std::basic_string_view<T>` is mapped to Python `str`
 *
 * There's no `get()` function as lifetime is not managed, but you can still use
 * `std::basic_string_view<T>` as function parameters as `ArgumentTraits` is specialized for it.
 *
 * @ingroup PyExportTraits
 */
template <typename T>
struct PyExportTraits<std::basic_string_view<T>>
{
    constexpr static const char* py_typing = "str";
 
    static PyObject* build(std::basic_string_view<T> v)
    {
        return impl::buildStringImpl(v.data(), v.size());
    }
};
 
 
/** @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<const char*>
{
    constexpr static const char* py_typing = "str | None";
 
    LASS_PYTHON_DLL static PyObject* build(const char* v);
};
 
 
/** @ingroup PyExportTraits
 */
template <size_t N>
struct PyExportTraits<const char [N]>
{
    static PyObject* build(const char* v)
    {
        static_assert(N > 1, "N should include the null-terminator");
        return impl::buildStringImpl(v, N - 1);
    }
};
 
 
/** @ingroup PyExportTraits
 */
template <size_t N>
struct PyExportTraits<char [N]> : PyExportTraits<const char [N]>
{
};
 
 
/** @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<std::string>
{
    constexpr static const char* py_typing = "str";
 
    LASS_PYTHON_DLL static PyObject* build(const std::string& v);
    LASS_PYTHON_DLL static int get(PyObject* obj, std::string& v);
};
 
 
/** @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<const wchar_t*>
{
    constexpr static const char* py_typing = "str | None";
 
    LASS_PYTHON_DLL static PyObject* build(const wchar_t* v);
};
 
 
/** @ingroup PyExportTraits
 */
template <size_t N>
struct PyExportTraits<const wchar_t [N]>
{
    static PyObject* build(const wchar_t* v)
    {
        return impl::buildStringImpl(v, N);
    }
};
 
 
/** @ingroup PyExportTraits
 */
template <size_t N>
struct PyExportTraits<wchar_t [N]>: PyExportTraits<const wchar_t [N]>
{
};
 
 
/** @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<std::wstring>
{
    constexpr static const char* py_typing = "str";
 
    LASS_PYTHON_DLL static PyObject* build(const std::wstring& v);
    LASS_PYTHON_DLL static int get(PyObject* obj, std::wstring& v);
};
 
 
#if LASS_HAVE_STD_U8STRING
#if __cpp_lib_char8_t
 
/** UTF-8 `const char8_t*` string is mapped to Python `str | None`, as it can be null.
 *
 * An empty string is mapped to an empty Python string, not to `None`.
 *
 * There's no `get()` function as lifetime is not managed, but you can still use `const char8_t*`
 * as function parameters as `ArgumentTraits` is specialized for it.
 *
 * @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<const char8_t*>
{
    constexpr static const char* py_typing = "str | None";
 
    LASS_PYTHON_DLL static PyObject* build(const char8_t* v);
};
 
 
/** @ingroup PyExportTraits
 */
template <size_t N>
struct PyExportTraits<const char8_t[N]>
{
    static PyObject* build(const char8_t* v)
    {
        return impl::buildStringImpl(v, N);
    }
};
 
 
/** @ingroup PyExportTraits
 */
template <size_t N>
struct PyExportTraits<char8_t[N]> : PyExportTraits<const char8_t[N]>
{
};
 
 
/** UTF-8 `std::u8string` is mapped to `str`
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<std::u8string>
{
    constexpr static const char* py_typing = "str";
 
    LASS_PYTHON_DLL static PyObject* build(const std::u8string& v);
    LASS_PYTHON_DLL static int get(PyObject* obj, std::u8string& v);
};
 
#endif
#endif
 
 
/** UTF-16 `const char16_t*` string is mapped to Python `str | None`, as it can be null.
 *
 * An empty string is mapped to an empty Python string, not to `None`.
 *
 * There's no `get()` function as lifetime is not managed, but you can still use `const char16_t*`
 * as function parameters as `ArgumentTraits` is specialized for it.
 *
 * @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<const char16_t*>
{
    constexpr static const char* py_typing = "str | None";
 
    LASS_PYTHON_DLL static PyObject* build(const char16_t* v);
};
 
 
/** @ingroup PyExportTraits
 */
template <size_t N>
struct PyExportTraits<const char16_t[N]>
{
    static PyObject* build(const char16_t* v)
    {
        return impl::buildStringImpl(v, N);
    }
};
 
 
/** @ingroup PyExportTraits
 */
template <size_t N>
struct PyExportTraits<char16_t[N]> : PyExportTraits<const char16_t[N]>
{
};
 
 
/** UTF-16 `std::u16string` is mapped to `str`
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<std::u16string>
{
    constexpr static const char* py_typing = "str";
 
    LASS_PYTHON_DLL static PyObject* build(const std::u16string& v);
    LASS_PYTHON_DLL static int get(PyObject* obj, std::u16string& v);
};
 
 
/** UTF-32 `const char32_t*` string is mapped to Python `str | None`, as it can be null.
 *
 * An empty string is mapped to an empty Python string, not to `None`.
 *
 * There's no `get()` function as lifetime is not managed, but you can still use `const char32_t*`
 * as function parameters as `ArgumentTraits` is specialized for it.
 *
 * @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<const char32_t*>
{
    constexpr static const char* py_typing = "str | None";
 
    LASS_PYTHON_DLL static PyObject* build(const char32_t* v);
};
 
 
/** @ingroup PyExportTraits
 */
template <size_t N>
struct PyExportTraits<const char32_t[N]>
{
    static PyObject* build(const char32_t* v)
    {
        return impl::buildStringImpl(v, N);
    }
};
 
 
/** @ingroup PyExportTraits
 */
template <size_t N>
struct PyExportTraits<char32_t[N]> : PyExportTraits<const char32_t[N]>
{
};
 
 
/** UTF-32 `std::u32string` is mapped to `str`
 *
 *  @ingroup PyExportTraits
 */
template <>
struct PyExportTraits<std::u32string>
{
    constexpr static const char* py_typing = "str";
 
    LASS_PYTHON_DLL static PyObject* build(const std::u32string& v);
    LASS_PYTHON_DLL static int get(PyObject* obj, std::u32string& v);
};
 
 
}
}
 
#endif
 
// EOF