document inheritance support and current limitations

Author: saidctb

CHANGELOG.md

@@ -55,7 +55,9 @@ release tags add a leading `v` to the package version.
 - Refreshed the README and website around the canonical
   **PRIK — Python Runtime Interop Kit** identity, with a concise FAQ, a fair
   PRIK-versus-f2py guide, clearer array guidance, and searchable real-library
-  examples, including a four-library capability and validation summary.
+  examples, including a four-library capability and validation summary, a
+  concise statement of current limitations, and a derived-type inheritance
+  walkthrough.
 - Hardened preprocessing, compiler-derived type probes, semantic policy
   completion, and multi-source build reporting so unsupported contracts fail
   earlier with clearer diagnostics.

README.md

@@ -37,6 +37,7 @@ the user guide, examples, and reference material.
 - [See it in action](#see-it-in-action)
 - [Key Features](#key-features)
 - [Performance](#performance)
+- [Current limitations](#current-limitations)
 - [Installation & Quick Start](#installation--quick-start)
 - [How it works](#how-it-works)
 - [Native Project Inputs](#native-project-inputs)
@@ -156,6 +157,16 @@ charts below come from the latest successfully deployed benchmark snapshot.
 
 [See the complete results, test environment, and one-command reproduction instructions.](https://pynumlab.github.io/prik/user/performance/)
 
+## Current limitations
+
+PRIK does not yet support:
+
+- arrays of derived types;
+- procedure pointers, including procedure-pointer module variables and callbacks
+  retained after the wrapped call; or
+- polymorphic outputs, mutable polymorphic arguments, polymorphic arrays,
+  unlimited polymorphism (`class(*)`), abstract types, and deferred bindings.
+
 ## Installation & Quick Start
 
 PRIK requires **Python 3.10 or newer**, NumPy, Python development headers,

docs/user/guide/wrapping-derived-types.md

@@ -250,6 +250,78 @@ For the complete mapping rules, see
 
 ---
 
+## Inheritance And Polymorphic Input Dispatch
+
+Fortran extension types generate a matching Python inheritance hierarchy.
+Inherited fields and methods remain available on the derived class, and an
+overridden type-bound method uses the derived implementation.
+
+```fortran
+type :: base_shape
+  real(8) :: size
+contains
+  procedure :: area => base_area
+  procedure :: set_size => base_set_size
+end type base_shape
+
+type, extends(base_shape) :: circle
+  real(8) :: radius
+contains
+  procedure :: area => circle_area
+end type circle
+
+contains
+
+real(8) function base_area(self) result(value)
+  class(base_shape), intent(in) :: self
+  value = self%size
+end function base_area
+
+subroutine base_set_size(self, value)
+  class(base_shape), intent(inout) :: self
+  real(8), intent(in) :: value
+  self%size = value
+end subroutine base_set_size
+
+real(8) function circle_area(self) result(value)
+  class(circle), intent(in) :: self
+  value = acos(-1.0_8) * self%radius * self%radius
+end function circle_area
+```
+
+For a wrapped module imported as `shapes`, the generated classes preserve that
+relationship:
+
+```python
+shape = shapes.circle()
+assert isinstance(shape, shapes.base_shape)
+
+shape.set_size(np.float64(5.0))
+shape.radius = np.float64(2.0)
+print(shape.size)    # inherited field: 5.0
+print(shape.area())  # overridden method: about 12.5664
+```
+
+A required scalar `class(base), intent(in)` argument accepts wrapped instances
+from the known base and descendant classes:
+
+```fortran
+real(8) function describe_shape(item) result(value)
+  class(base_shape), intent(in) :: item
+  value = item%area()
+end function describe_shape
+```
+
+```python
+print(shapes.describe_shape(shape))  # about 12.5664
+```
+
+This polymorphic boundary is intentionally limited to required scalar inputs.
+Polymorphic outputs, mutable arguments, arrays, allocatable or pointer scalars,
+and unlimited polymorphism (`class(*)`) are not supported.
+
+---
+
 ## Type-Bound Generics
 
 A type-bound generic groups several concrete methods under one Python method.

tests/fortran/derived_types/end_to_end/fixtures/finheritance_f90.f90

@@ -37,7 +37,7 @@ end subroutine base_set_size
   real(8) function circle_area(self) result(value)
     class(circle), intent(in) :: self
 
-    value = self%size + self%radius * self%radius
+    value = acos(-1.0_8) * self%radius * self%radius
   end function circle_area
 
   real(8) function box_area(self) result(value)

tests/fortran/derived_types/end_to_end/test_inheritance_and_polymorphism.py

@@ -44,8 +44,9 @@ def test_fortran_extension_types_generate_python_inheritance(
     circle.set_size(np.float64(5.0))
     circle.radius = np.float64(2.0)
     assert circle.size == np.float64(5.0)
-    assert circle.area() == np.float64(9.0)
-    assert module.describe_shape(circle) == np.float64(9.0)
+    expected_circle_area = np.float64(np.pi * circle.radius**2)
+    np.testing.assert_allclose(circle.area(), expected_circle_area)
+    np.testing.assert_allclose(module.describe_shape(circle), expected_circle_area)
 
     module.base_shape.set_size(circle, np.float64(7.0))
     assert circle.size == np.float64(7.0)