Add pointer-based variant

Author: znicholls

meson.build

@@ -52,6 +52,7 @@ if pyprojectwheelbuild_enabled
   # Injected with `script/inject-srcs-into-meson-build.py`
   srcs = files(
     'src/example_fgen_basic/error_v/creation_wrapper.f90',
+    'src/example_fgen_basic/error_v/error_v_ptr_based_wrapper.f90',
     'src/example_fgen_basic/error_v/error_v_wrapper.f90',
     'src/example_fgen_basic/get_wavelength_wrapper.f90',
   )
@@ -81,7 +82,6 @@ if pyprojectwheelbuild_enabled
     'src/example_fgen_basic/pyfgen_runtime/base_finalisable.py',
     'src/example_fgen_basic/pyfgen_runtime/exceptions.py',
     'src/example_fgen_basic/pyfgen_runtime/formatting.py',
-    'src/example_fgen_basic/runtime_helpers.py',
   )
 
   # The ancillary library,

src/example_fgen_basic/error_v/__init__.py

@@ -2,6 +2,6 @@
 Definition of an error value
 """
 
-from example_fgen_basic.error_v.error_v import ErrorV
+from example_fgen_basic.error_v.error_v import ErrorV, ErrorVPtrBased
 
-__all__ = ["ErrorV"]
+__all__ = ["ErrorV", "ErrorVPtrBased"]

src/example_fgen_basic/error_v/creation.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-from example_fgen_basic.error_v.error_v import ErrorV
+from example_fgen_basic.error_v.error_v import ErrorV, ErrorVPtrBased
 from example_fgen_basic.pyfgen_runtime.exceptions import CompiledExtensionNotFoundError
 
 try:
@@ -24,3 +24,16 @@ def create_error(inv: int) -> ErrorV:
     error = ErrorV(instance_index)
 
     return error
+
+
+def create_error_ptr_based(inv: int) -> ErrorVPtrBased:
+    """
+    Create an instance of error (a wrapper around our Fortran derived type)
+
+    Uses the pointer based logic
+    """
+    instance_ptr = m_error_v_creation_w.create_error_ptr_based(inv)
+
+    error = ErrorVPtrBased(instance_ptr)
+
+    return error

src/example_fgen_basic/error_v/creation_wrapper.f90

@@ -4,6 +4,8 @@
 !> Generation to be automated in future (including docstrings of some sort).
 module m_error_v_creation_w
 
+    use iso_c_binding, only: c_ptr, c_loc
+
     ! => allows us to rename on import to avoid clashes
     use m_error_v_creation, only: o_create_error => create_error
     use m_error_v, only: ErrorV
@@ -17,7 +19,7 @@ module m_error_v_creation_w
     implicit none
     private
 
-    public :: create_error
+    public :: create_error, create_error_ptr_based
 
 contains
 
@@ -51,4 +53,31 @@ subroutine create_error(inv, res_instance_index)
 
     end subroutine create_error
 
+    subroutine create_error_ptr_based(inv, res_instance_ptr)
+    ! Needs to be subroutine to have the created instance persist I think
+    ! (we can check)
+    ! function create_error(inv) result(res_instance_index)
+
+        integer, intent(in) :: inv
+        !! Input value to use to create the error
+
+        !f2py integer(8), intent(out) :: res_instance_ptr
+        type(c_ptr), intent(out) :: res_instance_ptr
+        !! Pointer to the resulting instance
+        !
+        ! This is the major trick for wrapping.
+        ! We return pointers (passed as integers) to Python rather than the instance itself.
+
+        type(ErrorV), pointer :: res
+
+        ! Question is: when does this get deallocated?
+        ! When we go out of scope?
+        ! If yes, that will be why we had to do this array thing.
+        allocate(res)
+        res = o_create_error(inv)
+
+        res_instance_ptr = c_loc(res)
+
+    end subroutine create_error_ptr_based
+
 end module m_error_v_creation_w

src/example_fgen_basic/error_v/error_v.py

@@ -10,12 +10,15 @@
 
 from example_fgen_basic.pyfgen_runtime.base_finalisable import (
     FinalisableWrapperBase,
+    FinalisableWrapperBasePtrBased,
     check_initialised,
+    check_initialised_ptr_based,
 )
 from example_fgen_basic.pyfgen_runtime.exceptions import CompiledExtensionNotFoundError
 
 try:
     from example_fgen_basic._lib import (  # type: ignore
+        m_error_v_ptr_based_w,
         m_error_v_w,
     )
 except (ModuleNotFoundError, ImportError) as exc:  # pragma: no cover
@@ -77,3 +80,62 @@ def message(self) -> str:
         ).decode()
 
         return message
+
+
+@define
+class ErrorVPtrBased(FinalisableWrapperBasePtrBased):
+    """
+    TODO: auto docstring e.g. "Wrapper around the Fortran :class:`ErrorV`"
+
+    Uses the pointer-based passing logic
+    """
+
+    # Bug in Ipython pretty hence have to put this on every object?
+    def _repr_pretty_(self, p: Any, cycle: bool) -> None:
+        """
+        Get pretty representation of self
+
+        Used by IPython notebooks and other tools
+        """
+        super()._repr_pretty_(p=p, cycle=cycle)
+
+    @property
+    def exposed_attributes(self) -> tuple[str, ...]:
+        """
+        Attributes exposed by this wrapper
+        """
+        return ("code", "message")
+
+    # TODO: from_build_args, from_new_connection, context manager, finalise
+
+    @property
+    @check_initialised_ptr_based
+    def code(self) -> int:
+        """
+        Error code
+
+        Returns
+        -------
+        :
+            Error code, retrieved from Fortran
+        """
+        code: int = m_error_v_ptr_based_w.iget_code(instance_ptr=self.instance_ptr)
+
+        return code
+
+    @property
+    @check_initialised_ptr_based
+    def message(self) -> str:
+        """
+        Error message
+
+        Returns
+        -------
+        :
+            Error message, retrieved from Fortran
+        """
+        message: str = m_error_v_ptr_based_w.iget_message(
+            instance_ptr=self.instance_ptr
+        ).decode()
+
+        return message

src/example_fgen_basic/error_v/error_v_ptr_based_wrapper.f90

@@ -0,0 +1,58 @@
+!> Wrapper for interfacing `m_error_v` with Python, using pointer only (no instance array)
+!>
+!> Written by hand here.
+!> Generation to be automated in future (including docstrings of some sort).
+module m_error_v_ptr_based_w
+
+    use iso_c_binding, only: c_ptr, c_f_pointer
+
+    use m_error_v, only: ErrorV
+
+    implicit none
+    private
+
+    public :: iget_code, iget_message
+
+contains
+
+    ! Full set of wrapping strategies to pass different types in e.g.
+    ! https://gitlab.com/magicc/fgen/-/blob/switch-to-uv/tests/test-data/exposed_attrs/src/exposed_attrs/exposed_attrs_wrapped.f90
+    ! (we will do a full re-write of the code which generates this,
+    ! but the strategies will probably stay as they are)
+    subroutine iget_code( &
+        instance_ptr, &
+        code &
+        )
+
+        !f2py integer(8), intent(in) :: instance_ptr
+        type(c_ptr), intent(in) :: instance_ptr
+
+        integer, intent(out) :: code
+
+        type(ErrorV), pointer :: instance
+
+        call c_f_pointer(instance_ptr, instance)
+
+        code = instance % code
+
+    end subroutine iget_code
+
+    subroutine iget_message( &
+        instance_ptr, &
+        message &
+        )
+
+        !f2py integer(8), intent(in) :: instance_ptr
+        type(c_ptr), intent(in) :: instance_ptr
+
+        character(len=128), intent(out) :: message
+
+        type(ErrorV), pointer :: instance
+
+        call c_f_pointer(instance_ptr, instance)
+
+        message = instance % message
+
+    end subroutine iget_message
+
+end module m_error_v_ptr_based_w

src/example_fgen_basic/meson.build

@@ -1,4 +1,7 @@
 srcs += files(
+  'error_v/creation.f90',
+  'error_v/error_v.f90',
+  'fpyfgen/base_finalisable.f90',
   'get_wavelength.f90',
   'kind_parameters.f90',
 )

src/example_fgen_basic/pyfgen_runtime/base_finalisable.py

@@ -163,3 +163,134 @@ def checked(
         return method(ref, *args, **kwargs)
 
     return checked  # type: ignore
+
+
+@define
+class FinalisableWrapperBasePtrBased(ABC):
+    """
+    Base class for Fortran derived type wrappers using the pointer-based passing
+    """
+
+    instance_ptr: int | None = None
+    """
+    Pointer to Fortran instance (technically a C pointer)
+    """
+
+    def __str__(self) -> str:
+        """
+        Get string representation of self
+        """
+        return to_str(
+            self,
+            self.exposed_attributes,
+        )
+
+    def _repr_pretty_(self, p: Any, cycle: bool) -> None:
+        """
+        Get pretty representation of self
+
+        Used by IPython notebooks and other tools
+        """
+        to_pretty(
+            self,
+            self.exposed_attributes,
+            p=p,
+            cycle=cycle,
+        )
+
+    def _repr_html_(self) -> str:
+        """
+        Get html representation of self
+
+        Used by IPython notebooks and other tools
+        """
+        return to_html(
+            self,
+            self.exposed_attributes,
+        )
+
+    @property
+    def initialized(self) -> bool:
+        """
+        Is the instance initialised, i.e. connected to a Fortran instance?
+        """
+        return self.instance_ptr is not None
+
+    @property
+    @abstractmethod
+    def exposed_attributes(self) -> tuple[str, ...]:
+        """
+        Attributes exposed by this wrapper
+        """
+        ...
+
+    # TODO: consider whether we need these
+    # @classmethod
+    # @abstractmethod
+    # def from_new_connection(cls) -> FinalisableWrapperBase:
+    #     """
+    #     Initialise by establishing a new connection with the Fortran module
+    #
+    #     This requests a new model index from the Fortran module and then
+    #     initialises a class instance
+    #
+    #     Returns
+    #     -------
+    #     New class instance
+    #     """
+    #     ...
+    #
+    # @abstractmethod
+    # def finalize(self) -> None:
+    #     """
+    #     Finalise the Fortran instance and set self back to being uninitialised
+    #
+    #     This method resets `self.instance_ptr` back to
+    #     `None`
+    #
+    #     Should be decorated with :func:`check_initialised`
+    #     """
+    #     # call to Fortran module goes here when implementing
+    #     self._uninitialise_instance_index()
+
+    def _uninitialise_instance_index(self) -> None:
+        self.instance_index = None
+
+
+WrapperPtrBased = TypeVar("WrapperPtrBased", bound=FinalisableWrapperBasePtrBased)
+
+
+def check_initialised_ptr_based(
+    method: Callable[Concatenate[WrapperPtrBased, P], T],
+) -> Callable[Concatenate[WrapperPtrBased, P], T]:
+    """
+    Check that the wrapper object has been initialised before executing the method
+
+    Parameters
+    ----------
+    method
+        Method to wrap
+
+    Returns
+    -------
+    :
+        Wrapped method
+
+    Raises
+    ------
+    InitialisationError
+        Wrapper is not initialised
+    """
+
+    @wraps(method)
+    def checked(
+        ref: WrapperPtrBased,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Any:
+        if not ref.initialized:
+            raise NotInitialisedError(ref, method)
+
+        return method(ref, *args, **kwargs)
+
+    return checked  # type: ignore