Add wrap-view annotation for in-place member modification

Adds a new `wrap-view` annotation that generates companion View classes
alongside regular wrapper classes. View classes provide direct access to
nested C++ objects without creating copies.

Key features:
- `obj.view()` returns a view for in-place member modification
- View properties return nested views (not copies) for wrapped classes
- Methods returning `T&` (mutable reference) return views on view class
- Views keep parent objects alive via Python reference chain

Implementation details:
- View classes use raw pointers + Python parent references (avoids
  Cython issues with shared_ptr aliasing across types)
- Methods marked wrap-ignore that return T& are still available on
  view classes (T& returns don't work on main classes due to Cython
  limitations, but work on view classes via pointer access)
- Forward references handled by pre-computing classes_with_views

Includes unit tests for code generation and integration tests that
compile actual Cython code and verify runtime behavior.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: timosachsenberg

autowrap/CodeGenerator.py

@@ -76,6 +76,10 @@ class is the same as the name of the C++ class.
     There are a few additional hints you can give to the wrapper, for classes these are:
         - wrap-ignore: will not create a wrapper for this class (e.g. abstract
                        base class that needs to be known to Cython but cannot be wrapped)
+        - wrap-view: generate a companion ${ClassName}View class that provides
+                     in-place access to members. The view class allows direct
+                     modification of nested objects without copies. Methods
+                     returning T& (mutable reference) return views instead of copies.
         - wrap-manual-memory: will allow the user to provide manual memory
                               management of self.inst, therefore the class will
                               not provide the automated __dealloc__ and inst
@@ -173,6 +177,7 @@ class ResolvedClass(object):
     cpp_decl: PXDParser.CppClassDecl
     ns: AnyStr
     wrap_ignore: bool
+    wrap_view: bool
     no_pxd_import: bool
     wrap_manual_memory: Union[bool, List[AnyStr]]
     wrap_hash: List[AnyStr]
@@ -193,6 +198,7 @@ def __init__(self, name, methods, attributes, decl, instance_map, local_map):
         self.ns = get_namespace(decl.pxd_path, DEFAULT_NAMESPACE)
 
         self.wrap_ignore = decl.annotations.get("wrap-ignore", False)
+        self.wrap_view = decl.annotations.get("wrap-view", False)
         self.no_pxd_import = decl.annotations.get("no-pxd-import", False)
         self.wrap_manual_memory = decl.annotations.get("wrap-manual-memory", [])
         # fix previous code where we had a bool ...
@@ -560,8 +566,14 @@ def _resolve_class_decl(class_decl, typedef_mapping, i_mapping):
         for mname, mdcls in class_decl.methods.items():
             for mdcl in mdcls:
                 ignore = mdcl.annotations.get("wrap-ignore", False)
+                # Keep wrap-ignore methods that return mutable references (T&)
+                # since these are useful for wrap-view generation even when
+                # the main class method is ignored. Filter out other wrap-ignore methods.
                 if ignore:
-                    continue
+                    result_type = mdcl.result_type
+                    if not (result_type.is_ref and not result_type.is_const):
+                        # Not a mutable reference return - skip as before
+                        continue
                 if mdcl.name == class_decl.name:
                     r_method = _resolve_constructor(cinst_name, mdcl, i_mapping, local_mapping)
                 else:

autowrap/DeclResolver.py

@@ -159,6 +159,11 @@ and for methods by putting them on the same line. The currently supported
 directives are:
 
 - `wrap-ignore`: Will not create a wrapper for this function or class (e.g. abstract base class that needs to be known to Cython but cannot be wrapped)
+- `wrap-view`: Generate a companion `${ClassName}View` class that provides in-place access to members. The main wrapper class returns copies (safe, but modifications don't affect the original). The view class holds a reference to the parent and allows direct modification:
+  - Public attributes become view properties (getters return views of nested objects, setters modify in-place)
+  - Methods returning `T&` (mutable reference) return views instead of copies
+  - Views keep the parent object alive via shared_ptr
+  - Use `obj.view()` on the main class to get a view instance
 - `wrap-iter-begin`: For begin iterators
 - `wrap-iter-end`: For end iterators
 - `wrap-attach`: Attach to a specific class (can be used for static functions or nested classes)
@@ -280,6 +285,34 @@ namespace std {
 }
 ```
 
+#### wrap-view Example
+
+The `wrap-view` directive generates a companion view class for in-place member modification:
+
+```cython
+    cdef cppclass Inner:
+        # wrap-view
+        int value
+
+    cdef cppclass Outer:
+        # wrap-view
+        Inner & getInner()   # Mutable reference getter
+        Inner inner_member   # Public attribute
+```
+
+This generates `Inner`, `InnerView`, `Outer`, and `OuterView` classes. Usage:
+
+```python
+>>> outer = Outer()
+>>> outer.inner_member.value = 42  # Modifies a COPY - original unchanged!
+>>> view = outer.view()
+>>> view.inner_member.value = 42   # Modifies IN-PLACE - original changed!
+>>> inner_view = view.getInner()   # Returns InnerView, not copy
+>>> inner_view.value = 100         # In-place modification
+```
+
+The view keeps the parent alive - you can safely store and use views as long as needed.
+
 ### Docstrings
 
 Docstrings can be added to classes and methods using the `wrap-doc` statement. Multi line docs are supported with