You are viewing a plain text version of this content. The canonical link for it is here.
Posted to discuss-archive@tvm.apache.org by "junrushao (via GitHub)" <gi...@apache.org> on 2026/07/13 21:16:07 UTC

[PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

junrushao opened a new pull request, #663:
URL: https://github.com/apache/tvm-ffi/pull/663

   Architecture:
   - Resolve annotations from each declaring class so forward references, recursive classes, and mixins no longer depend on merged inherited annotations.
   - Centralize typed reflection conversion in TypeAttr and ObjectDef while native object-valued fields receive explicit placement construction and destruction.
   - Carry nested field paths through conversion failures and compute init-only properties after FFI-backed construction.
   
   Public Interfaces:
   - Add init_property for values derived once after dataclass initialization.
   - Add reflection conversion hooks for type attributes and object definitions.
   - Make py_class use tree structural equality by default; callers can still opt out explicitly with structural_eq=None.
   
   UI/UX:
   - None.
   
   Behavioral Changes:
   - Dataclass field resolution now respects the class that declares each field.
   - Native field conversion reports the complete path to a failing nested value.
   - Device strings and reflected ancestor types use the shared conversion path.
   
   Docs:
   - Update the structural equality guide for the new py_class default.
   - Keep lower-level reflection and init_property behavior documented through API comments and focused tests; a broader narrative guide can follow separately.
   
   Tests:
   - Clean editable C++/Cython build completed successfully.
   - 1103 focused dataclass, structural, converter, typed-method, and function tests passed; 2 expected failures remained expected.
   - Scoped pre-commit hooks passed for all files in this boundary.
   
   Untested Edge Cases:
   - Rust bindings, Windows/MSVC, and the full cross-platform test matrix were not run for this intermediate boundary.
   - Stub regeneration exposes pre-existing drift in mutable-container annotations and an omitted test helper, so those unrelated generated edits are deferred.
   
   BREAKING CHANGE: py_class now defaults to tree structural equality and field resolution follows each declaring class. Extensions that depend on the previous default or annotation-merging behavior must opt out or update their declarations and rebuild C++/Cython artifacts.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3575941478


##########
include/tvm/ffi/type_traits.h:
##########
@@ -536,6 +537,88 @@ struct TypeTraits<void*> : public TypeTraitsBase {
   }
 };
 
+namespace details {
+
+TVM_FFI_INLINE static std::optional<std::string_view> TryGetStringViewFromAny(
+    const TVMFFIAny* src) {
+  if (src->type_index == TypeIndex::kTVMFFIRawStr) {
+    return std::string_view(src->v_c_str);
+  }
+  if (src->type_index == TypeIndex::kTVMFFISmallStr) {
+    TVMFFIByteArray bytes = TVMFFISmallBytesGetContentByteArray(src);
+    return std::string_view(bytes.data, bytes.size);
+  }
+  if (src->type_index == TypeIndex::kTVMFFIStr) {
+    TVMFFIByteArray* bytes = TVMFFIBytesGetByteArrayPtr(src->v_obj);
+    return std::string_view(bytes->data, bytes->size);
+  }
+  return std::nullopt;
+}
+
+TVM_FFI_INLINE static std::optional<DLDeviceType> TryParseDLDeviceType(std::string_view name) {
+  if (name == "llvm" || name == "cpu" || name == "c" || name == "test") return kDLCPU;
+  if (name == "cuda" || name == "nvptx") return kDLCUDA;
+  if (name == "cl" || name == "opencl") return kDLOpenCL;
+  if (name == "vulkan") return kDLVulkan;
+  if (name == "metal") return kDLMetal;
+  if (name == "vpi") return kDLVPI;
+  if (name == "rocm") return kDLROCM;
+  if (name == "ext_dev") return kDLExtDev;
+  if (name == "hexagon") return kDLHexagon;
+  if (name == "webgpu") return kDLWebGPU;
+  if (name == "maia") return kDLMAIA;
+  if (name == "trn") return kDLTrn;
+  return std::nullopt;
+}
+
+TVM_FFI_INLINE static std::optional<int32_t> TryParseDLDeviceIndex(std::string_view index) {
+  if (index.empty()) return std::nullopt;
+  int64_t sign = 1;
+  size_t pos = 0;
+  if (index[0] == '-') {
+    sign = -1;
+    pos = 1;
+  }
+  if (pos >= index.size()) return std::nullopt;
+  int64_t value = 0;
+  for (; pos < index.size(); ++pos) {
+    char ch = index[pos];
+    if (ch < '0' || ch > '9') return std::nullopt;
+    value = value * 10 + (ch - '0');
+    if (value > std::numeric_limits<int32_t>::max()) return std::nullopt;
+  }
+  value *= sign;
+  if (value < std::numeric_limits<int32_t>::min() || value > std::numeric_limits<int32_t>::max()) {
+    return std::nullopt;
+  }
+  return static_cast<int32_t>(value);
+}
+
+TVM_FFI_INLINE static std::optional<DLDevice> TryStringViewToDLDevice(std::string_view str) {
+  size_t space_pos = str.find(' ');
+  if (space_pos != std::string_view::npos) {
+    str = str.substr(0, space_pos);
+  }
+  size_t colon_pos = str.find(':');
+  std::string_view name = colon_pos == std::string_view::npos ? str : str.substr(0, colon_pos);
+  if (name.empty()) return std::nullopt;
+  if (str.find(':', colon_pos == std::string_view::npos ? str.size() : colon_pos + 1) !=
+      std::string_view::npos) {
+    return std::nullopt;
+  }
+  std::optional<DLDeviceType> device_type = TryParseDLDeviceType(name);

Review Comment:
   Done in 2979977. I moved the device string parsing and `TypeTraits<DLDevice>` into the new public `tvm/ffi/device.h`, included it from the umbrella/tensor headers and direct consumers, and added focused C++ coverage for native, valid-string, and invalid-string conversions. Thanks!



##########
include/tvm/ffi/reflection/registry.h:
##########


Review Comment:
   Done in 2979977. `TypeAttrDef::attr` now delegates to `RegisterTypeAttrValue(type_index_, name, std::move(value))`, so type-attribute values share the centralized registration path. Thanks!



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3576403344


##########
python/tvm_ffi/cython/function.pxi:
##########
@@ -398,8 +398,10 @@ cdef int TVMFFIPyArgSetterDType_(
 ) except -1:
     """Setter for dtype"""
     cdef object arg = <object>py_arg
-    # dtype is a subclass of str, so this check occur before str
-    arg = arg._tvm_ffi_dtype
+    # tvm_ffi.dtype is a subclass of str, so this check occurs before str.
+    # The internal DataType helper can also be produced by TypeSchema converters.
+    if not isinstance(arg, DataType):

Review Comment:
   Done. I split the cached paths: internal `core.DataType` now uses a dedicated `TVMFFIPyArgSetterCDataType_` that directly copies the `DLDataType` struct, while public `tvm_ffi.dtype` uses the unwrapping setter. The one-time factory selects between them, so the cached hot path no longer pays an `isinstance` cost. I added a direct `core.DataType` FFI round-trip regression; the generated Cython code contains a direct field access with no type check.



##########
python/tvm_ffi/utils/descriptors.py:
##########
@@ -0,0 +1,80 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Descriptor utilities for the tvm_ffi Python package."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from typing import Any, Callable, Generic, TypeVar, overload
+
+_T = TypeVar("_T")
+
+
+def _get_forward_annotations(obj: Any) -> dict[str, Any]:
+    """Return Python 3.14+ annotations without forcing unresolved names."""
+    annotationlib: Any = importlib.import_module("annotationlib")
+    return annotationlib.get_annotations(obj, format=annotationlib.Format.FORWARDREF)
+
+
+class init_property(Generic[_T]):
+    """Auto-registered C++ field with eager computation at ``__init__`` time.

Review Comment:
   Done. I moved `init_property` into `dataclasses/field.py`, export it as `tvm_ffi.dataclasses.init_property`, and updated `py_class` plus the tests to use the dataclasses API. The generic `utils.descriptors` module and its utils re-export are removed; no compatibility shim is retained because this API is new in this unmerged PR.



##########
include/tvm/ffi/device.h:
##########
@@ -0,0 +1,155 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/*!
+ * \file tvm/ffi/device.h
+ * \brief Device handling.
+ */
+#ifndef TVM_FFI_DEVICE_H_
+#define TVM_FFI_DEVICE_H_
+
+#include <dlpack/dlpack.h>
+#include <tvm/ffi/string.h>
+#include <tvm/ffi/type_traits.h>
+
+#include <cstdint>
+#include <limits>
+#include <optional>
+#include <string>
+#include <string_view>
+
+namespace tvm {
+namespace ffi {
+namespace details {
+
+TVM_FFI_INLINE static std::optional<DLDeviceType> TryParseDLDeviceType(std::string_view name) {
+  if (name == "llvm" || name == "cpu" || name == "c" || name == "test") return kDLCPU;

Review Comment:
   Agreed. The core String/Any-to-DLDevice fallback now recognizes only the canonical `cpu`, `cuda`, and `opencl` names. I left the existing broader Python `Device` name handling unchanged, since this request is specifically about the core conversion boundary. The C++ test now rejects every removed target/backend alias while keeping native `DLDevice` passthrough unchanged.



##########
tests/cpp/test_device.cc:
##########
@@ -0,0 +1,60 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+#include <gtest/gtest.h>
+#include <tvm/ffi/any.h>
+#include <tvm/ffi/device.h>
+
+namespace {
+
+using namespace tvm::ffi;
+
+TEST(Device, AnyConversion) {
+  DLDevice device{kDLCUDA, 1};
+  AnyView view = device;
+
+  DLDevice converted = view.cast<DLDevice>();
+  EXPECT_EQ(converted.device_type, kDLCUDA);
+  EXPECT_EQ(converted.device_id, 1);
+}
+
+TEST(Device, AnyConversionWithString) {
+  AnyView cpu_view = "cpu";
+  DLDevice cpu = cpu_view.cast<DLDevice>();
+  EXPECT_EQ(cpu.device_type, kDLCPU);
+  EXPECT_EQ(cpu.device_id, 0);
+
+  Any cuda_any = String("cuda:3");
+  DLDevice cuda = cuda_any.cast<DLDevice>();
+  EXPECT_EQ(cuda.device_type, kDLCUDA);
+  EXPECT_EQ(cuda.device_id, 3);
+
+  AnyView opencl_view = "opencl:-2";

Review Comment:
   Agreed. Textual device indices are now digits-only, so negative or explicitly signed spellings are rejected and the sign/minimum-range branches are gone. The tests cover negative rejection, acceptance of `INT32_MAX`, and rejection of `INT32_MAX + 1`.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "tqchen (via GitHub)" <gi...@apache.org>.
tqchen commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3575710057


##########
include/tvm/ffi/reflection/registry.h:
##########


Review Comment:
   call RegisterTypeAttrValue



##########
include/tvm/ffi/reflection/registry.h:
##########
@@ -1004,16 +1104,32 @@ class TypeAttrDef : public ReflectionDefBase {
    *
    * \return The TypeAttrDef object.
    */
-  template <typename Func>
+  template <typename Func, std::enable_if_t<!std::is_convertible_v<Func&&, AnyView> &&
+                                                !std::is_convertible_v<std::decay_t<Func>, AnyView>,
+                                            int> = 0>
   TypeAttrDef& def(const char* name, Func&& func) {
-    TVMFFIByteArray name_array = {name, std::char_traits<char>::length(name)};
     ffi::Function ffi_func =
         GetMethod(std::string(type_key_) + "." + name, std::forward<Func>(func));
-    TVMFFIAny value_any = AnyView(ffi_func).CopyToTVMFFIAny();
-    TVM_FFI_CHECK_SAFE_CALL(TVMFFITypeRegisterAttr(type_index_, &name_array, &value_any));
+    RegisterTypeAttrValue(type_index_, name, ffi_func);
     return *this;
   }
 
+  /*!
+   * \brief Register the standard AnyView conversion type attribute.
+   *
+   * \tparam TSelf The type produced by the conversion.
+   *
+   * \return The TypeAttrDef object.
+   */
+  template <typename TSelf>
+  TVM_FFI_INLINE TypeAttrDef& def_convert() {
+    if constexpr (details::HasContainerType<TSelf>::value) {
+      static_assert(std::is_same_v<typename TSelf::ContainerType, Class>,
+                    "TSelf::ContainerType must match TypeAttrDef's object type");
+    }
+    return def(type_attr::kConvert, &details::FFIConvertFromAnyViewToObjectRef<TSelf>);

Review Comment:
   this seems to be specialized for convert, ideally we dpn't bloat the api here per ffi key, 
   
   def(type_attr::kConvert, &details::FFIConvertFromAnyViewToObjectRef<TSelf>);
   
   is a fast enough oneliner that i think we should remove this one also removes need of ContainerType



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3576147841


##########
python/tvm_ffi/dataclasses/py_class.py:
##########
@@ -521,24 +402,25 @@ def _register_fields_into_type(
     # ``tvm_ffi.dataclasses.fields()`` compat layer can recover defaults
     # and default_factory values.  _register_fields preserves order, so
     # own_fields and type_info.fields line up 1:1.
+    assert len(own_fields) == len(type_info.fields)
     for py_field, type_field in zip(own_fields, type_info.fields):
         type_field.dataclass_field = py_field

Review Comment:
   it makes no difference



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao merged PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "tqchen (via GitHub)" <gi...@apache.org>.
tqchen commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3576227354


##########
python/tvm_ffi/cython/function.pxi:
##########
@@ -398,8 +398,10 @@ cdef int TVMFFIPyArgSetterDType_(
 ) except -1:
     """Setter for dtype"""
     cdef object arg = <object>py_arg
-    # dtype is a subclass of str, so this check occur before str
-    arg = arg._tvm_ffi_dtype
+    # tvm_ffi.dtype is a subclass of str, so this check occurs before str.
+    # The internal DataType helper can also be produced by TypeSchema converters.
+    if not isinstance(arg, DataType):

Review Comment:
   more efficient way hre is to allow a separate setter for CDataType, so not paying isinstance cost here



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3574337253


##########
python/tvm_ffi/_dunder.py:
##########
@@ -104,6 +114,22 @@ def __init__(self: Any, *args: Any, **kwargs: Any) -> None:
     return __init__
 
 
+def _collect_init_property_funcs(type_cls: type) -> list[tuple[str, Callable[..., Any]]]:
+    """Collect ``(name, func)`` pairs for all ``init_property`` fields in MRO order.
+
+    Walks from the most specific class toward the root.  Child definitions take
+    precedence over parent definitions of the same name (first-seen wins).
+    """
+    funcs: list[tuple[str, Callable[..., Any]]] = []
+    seen: set[str] = set()
+    for cls in type_cls.__mro__:
+        for name, func in cls.__dict__.get("__ffi_init_property_funcs__", {}).items():
+            if name not in seen:
+                funcs.append((name, func))
+                seen.add(name)
+    return funcs

Review Comment:
   Fixed in 36ee686. _collect_init_property_funcs now walks the reversed MRO into an insertion-ordered dict, so parent properties are initialized before child properties while child definitions still replace inherited ones. I added regressions for a child property depending on a parent property and for child override selection. The complete test_dataclass_py_class.py file passes (386 passed, 1 version-gated skip on Python 3.13), and the Python 3.14 TestInitProperty group passes 9/9. Thanks!



##########
python/tvm_ffi/utils/descriptors.py:
##########
@@ -0,0 +1,61 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Descriptor utilities for the tvm_ffi Python package."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Generic, TypeVar, overload
+
+_T = TypeVar("_T")
+
+
+class init_property(Generic[_T]):
+    """Auto-registered C++ field with eager computation at ``__init__`` time.
+
+    ``@py_class`` detects ``init_property`` descriptors and registers each one
+    as ``field(init=False, structural_eq="ignore")``, so the computed value
+    lives in C++ object storage and is accessible cross-language.  The value
+    is computed once — immediately after ``__ffi_init__`` — and stored via the
+    field's C++ slot.  Subsequent reads go directly to C++ memory.
+
+    The return annotation of the decorated function is injected into the class
+    ``__annotations__`` during class body execution so the field resolution
+    machinery picks it up automatically.  If no return annotation is present,
+    ``typing.Any`` is used.
+    """
+
+    def __init__(self, func: Callable[[Any], _T]) -> None:
+        self.func = func
+        self.name: str | None = None
+        self._return_annotation: Any = func.__annotations__.get("return")
+
+    @overload
+    def __get__(self, obj: None, objtype: type) -> init_property[_T]: ...
+    @overload
+    def __get__(self, obj: object, objtype: type) -> _T: ...
+    def __get__(self, obj: object | None, objtype: type) -> _T | init_property[_T]:
+        return self
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self.name = name
+
+        ann = self._return_annotation if self._return_annotation is not None else Any
+        # Inject into the owner's own __annotations__ so on_fields_resolved
+        # processes this name as a typed field.
+        if "__annotations__" not in owner.__dict__:
+            owner.__annotations__ = {}
+        owner.__annotations__[name] = ann

Review Comment:
   Fixed in 36ee686. On Python 3.14+, both the decorated function return annotation and the owner annotations now use annotationlib.get_annotations with Format.FORWARDREF, then the computed field is merged into the complete mapping. I used this instead of directly mutating owner.__annotations__ because direct access can eagerly evaluate unresolved self or forward references during __set_name__. I added a no-future PEP 749 regression preserving a normal field, an unresolved self-referential field, and the init_property return annotation. The Python 3.14 TestInitProperty group passes 9/9. Thanks!



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "gemini-code-assist[bot] (via GitHub)" <gi...@apache.org>.
gemini-code-assist[bot] commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3576031961


##########
python/tvm_ffi/dataclasses/_resolve_fields.py:
##########
@@ -0,0 +1,462 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Forward-annotation resolution for ``@py_class`` registration.
+
+``@py_class`` registers a Python type before it resolves field annotations, so
+self-referential and mutually recursive annotations can refer to classes that
+are already present in the FFI type registry.  This module owns that early
+registration step, the per-module local namespace used by
+``typing.get_type_hints``, and the queue of classes whose annotations must be
+retried after later definitions become available.
+
+When a class is ready to finalize, this module lazily imports
+``py_class.on_fields_resolved``.  Keeping the finalizer import local preserves
+the boundary between annotation resolution and field registration while avoiding
+a top-level import cycle.
+"""
+
+from __future__ import annotations
+
+import sys
+import typing
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .. import core
+from .field import KW_ONLY
+
+if TYPE_CHECKING:
+    from ..core import TypeInfo
+else:
+    TypeInfo = Any
+
+ResolvedFields = tuple[list[type], dict[type, dict[str, Any]]]
+
+
+# ---------------------------------------------------------------------------
+# Module-level state
+# ---------------------------------------------------------------------------
+#
+# ``@py_class`` registration happens in two phases:
+#
+#   Phase 1 (register_type_without_fields)
+#       Allocates a C-level type index and inserts the class into the
+#       global type registry.  This must happen early so that self-
+#       referential and mutually-referential annotations can resolve
+#       the class via ``TypeSchema.from_annotation()``.  Phase 1 always
+#       succeeds or raises immediately for invalid parents.  Decorator
+#       options are stored by py_class.py on ``TypeInfo._decorator_args``.
+#
+#   Phase 2 (py_class.on_fields_resolved)
+#       Resolves string annotations via ``typing.get_type_hints``,
+#       returns per-owner resolved hints, and asks py_class.py to
+#       materialize ``Field`` objects, register fields/methods/type
+#       attributes with the Cython layer, and install dataclass dunders.
+#
+#       If ``get_type_hints`` raises ``NameError`` (forward reference
+#       not yet defined), the class is added to ``_PENDING_CLASSES``
+#       and retried after each successful phase-2.  If phase-2 fails
+#       for any other reason, ``rollback_registration`` undoes phase-1
+#       so the type key can be reused.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _PendingClass:
+    """Resolution state for a class waiting on unresolved annotations.
+
+    Only data needed to retry annotation resolution is stored here.  Decorator
+    options live on ``type_info._decorator_args`` so deferred and immediate
+    finalization use the same source of truth.
+    """
+
+    cls: type
+    type_info: TypeInfo
+    globalns: dict[str, Any]
+
+
+#: Classes whose phase-2 (field registration) was deferred because
+#: ``typing.get_type_hints`` raised ``NameError`` on an unresolved
+#: forward reference.  Retried after each successful phase-2 via
+#: :func:`flush_pending`.
+_PENDING_CLASSES: list[_PendingClass] = []
+
+#: Per-module mapping of ``class.__name__ → class`` for every
+#: ``@py_class``-decorated type.  Used as *localns* when resolving
+#: annotations so that mutual references between classes in the same
+#: module work even before the second class is assigned to the module
+#: variable by Python.
+_PY_CLASS_BY_MODULE: dict[str, dict[str, type]] = {}
+
+
+class _KWOnlyAnnotation:
+    """Type-valued stand-in accepted by ``typing.get_type_hints``."""
+
+
+def _is_kw_only_annotation(annotation: Any) -> bool:
+    if annotation is KW_ONLY or annotation is _KWOnlyAnnotation:
+        return True
+    if isinstance(annotation, str):
+        return annotation == "KW_ONLY" or annotation.endswith(".KW_ONLY")
+    forward_arg = getattr(annotation, "__forward_arg__", None)
+    if isinstance(forward_arg, str):
+        return forward_arg == "KW_ONLY" or forward_arg.endswith(".KW_ONLY")
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Phase 1: type registration
+# ---------------------------------------------------------------------------
+
+
+def _registered_type_info(cls: type) -> TypeInfo | None:
+    """Return the TypeInfo registered directly for *cls*, not inherited metadata."""
+    info = core._type_cls_to_type_info(cls)
+    if info is not None:
+        return info
+    return cls.__dict__.get("__tvm_ffi_type_info__", None)
+
+
+def register_type_without_fields(cls: type, type_key: str | None) -> TypeInfo:
+    """Register ``cls`` in the FFI type registry before resolving fields.
+
+    The returned :class:`~tvm_ffi.core.TypeInfo` has a type index, type key, and
+    Python class binding, but no field metadata yet.  This early registration is
+    what lets ``TypeSchema.from_annotation`` resolve references to ``cls`` while
+    the decorator is still running.
+
+    The class is also inserted into the module-local annotation namespace used
+    by :func:`resolve_type_hints_by_owner`, allowing sibling ``@py_class``
+    declarations in the same module to reference each other before the second
+    class has been assigned to the module global by Python.
+    """
+    parent_info = next(
+        (info for base in cls.__mro__[1:] if (info := _registered_type_info(base)) is not None),
+        None,
+    )
+    if parent_info is None:
+        raise TypeError(
+            f"{cls.__name__} must inherit from a registered FFI Object type (e.g. tvm_ffi.Object)"
+        )
+    if type_key is None:
+        type_key = f"{cls.__module__}.{cls.__qualname__}"
+    info = core._register_py_class(parent_info, type_key, cls)
+    setattr(cls, "__tvm_ffi_type_info__", info)
+    # Register in resolution namespace so sibling classes can find us.
+    _PY_CLASS_BY_MODULE.setdefault(cls.__module__, {})[cls.__name__] = cls
+    return info
+
+
+def rollback_registration(cls: type, type_info: TypeInfo) -> None:
+    """Undo Python-side state from :func:`register_type_without_fields`.
+
+    The C-level type index is permanently consumed (cannot be reclaimed),
+    but the Python-level registry dicts are cleaned up so a retry with
+    the same type key does not hit "already registered".  The dataclass marker
+    is also removed because failed phase-2 finalization means the class is not a
+    usable FFI dataclass.
+    """
+    # Remove from the Cython-level registry dicts (TYPE_KEY_TO_INFO,
+    # TYPE_CLS_TO_INFO, TYPE_INDEX_TO_INFO, TYPE_INDEX_TO_CLS).
+    core._rollback_py_class(type_info)  # ty: ignore[unresolved-attribute]
+    # Remove from our own module-level resolution namespace.
+    _PY_CLASS_BY_MODULE.get(cls.__module__, {}).pop(cls.__name__, None)
+    for attr in ("__tvm_ffi_type_info__", "__ffi_is_dataclass__"):
+        try:
+            delattr(cls, attr)
+        except AttributeError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Annotation resolution
+# ---------------------------------------------------------------------------
+
+
+def own_annotations(cls: type) -> dict[str, Any]:
+    """Return annotations declared directly on ``cls`` without MRO merging."""
+    # Python 3.14+ (PEP 749): annotations are lazily evaluated via
+    # __annotate__ and no longer stored directly in __dict__.  getattr()
+    # triggers evaluation and returns per-class annotations correctly.
+    # On Python < 3.14, getattr() follows MRO and returns *parent*
+    # annotations when the child has none — use __dict__ to avoid that.
+    if sys.version_info >= (3, 14):
+        return getattr(cls, "__annotations__", {})
+    return cls.__dict__.get("__annotations__", {})
+
+
+def _field_owner_classes(cls: type) -> list[type]:
+    """Return local MRO entries whose annotations become fields on ``cls``.
+
+    A Python subclass of a registered FFI parent may include unregistered mixin
+    bases before the registered parent.  Those mixin annotations are owned by
+    the new Python type and should be registered together with ``cls``.  Fields
+    already represented by the nearest registered parent are excluded.
+    """
+    registered_parent = next(
+        (b for b in cls.__mro__[1:] if _registered_type_info(b) is not None), object
+    )
+    represented = set(registered_parent.__mro__)
+    return [
+        b
+        for b in reversed(cls.__mro__)
+        if b is not object and b not in represented and own_annotations(b)
+    ]
+
+
+def _build_localns(cls: type, *, cross_module: bool = False) -> dict[str, Any]:
+    """Build the localns dict for resolving ``cls``'s annotations.
+
+    By default, includes only classes from ``cls.__module__``, preserving
+    standard Python name resolution semantics.  When ``cross_module=True``,
+    also includes classes from all other registered modules as a fallback
+    — this is needed when ``cls`` has a forward reference to a class in
+    another module that can't appear in ``cls.__module__``'s globals due
+    to a circular import (e.g. the target is imported only under
+    ``if TYPE_CHECKING:``).
+
+    Cross-module entries are added with ``setdefault`` so same-module
+    classes and the class itself always take precedence over foreign
+    classes with the same ``__name__``.
+    """
+    localns = dict(_PY_CLASS_BY_MODULE.get(cls.__module__, {}))
+    localns[cls.__name__] = cls
+    if cross_module:
+        for mod_name, mod_classes in list(_PY_CLASS_BY_MODULE.items()):
+            if mod_name == cls.__module__:
+                continue
+            for name, klass in mod_classes.items():
+                localns.setdefault(name, klass)
+    return localns
+
+
+def _resolve_own_type_hints(
+    owner: type,
+    globalns: dict[str, Any],
+    localns: dict[str, Any],
+) -> dict[str, Any]:
+    """Resolve only annotations declared directly on ``owner``.
+
+    ``typing.get_type_hints(cls)`` merges annotations across the full MRO.
+    That is wrong for py_class phase 2 because inherited C++/c_class fields
+    are already registered by the parent type.  Resolving only the owner
+    annotations also avoids evaluating parent annotations in the child
+    module's namespace.
+
+    Python 3.10's ``typing.get_type_hints`` rejects ``dataclasses.KW_ONLY``
+    because it is a singleton, not a type.  Replace it in the temporary shim
+    annotations, then restore it in the resolved hints.
+    """
+    annotations = own_annotations(owner)
+    if not annotations:
+        return {}
+    shim_annotations = dict(annotations)
+    kw_only_names: list[str] = []
+    for name, annotation in annotations.items():
+        if _is_kw_only_annotation(annotation):
+            shim_annotations[name] = _KWOnlyAnnotation
+            kw_only_names.append(name)
+    shim = type(
+        f"_{owner.__name__}OwnAnnotations",
+        (),
+        {"__annotations__": shim_annotations, "__module__": owner.__module__},
+    )
+    kwargs: dict[str, Any] = {"globalns": globalns, "localns": localns}
+    if sys.version_info >= (3, 11):
+        kwargs["include_extras"] = True
+    hints = typing.get_type_hints(shim, **kwargs)
+    for name in kw_only_names:
+        hints[name] = KW_ONLY
+    return hints
+
+
+def resolve_type_hints_by_owner(
+    cls: type,
+    globalns: dict[str, Any],
+) -> ResolvedFields | None:
+    """Resolve field annotations grouped by owner class.
+
+    Returns ``(owners, hints_by_owner)`` when every annotation can be resolved.
+    Returns :data:`None` when a forward reference is still unavailable, signaling
+    that the caller should defer field registration and retry later.
+    """
+    # Resolve string annotations to types; return None (defer) on NameError.
+    #
+    # First try with module-scoped localns (standard Python name resolution).
+    # On NameError, retry with a cross-module localns that includes classes
+    # from every registered module — this handles circular imports where the
+    # target of a forward reference is imported only under TYPE_CHECKING and
+    # therefore never enters the declaring module's globals.
+    owners = _field_owner_classes(cls)
+    localns = _build_localns(cls)
+    localns.update({owner.__name__: owner for owner in owners})
+    try:
+        hints_by_owner = {
+            owner: _resolve_own_type_hints(
+                owner,
+                getattr(sys.modules.get(owner.__module__, None), "__dict__", globalns),
+                localns,
+            )
+            for owner in owners
+        }
+    except (NameError, AttributeError):
+        localns = _build_localns(cls, cross_module=True)
+        localns.update({owner.__name__: owner for owner in owners})
+        try:
+            hints_by_owner = {
+                owner: _resolve_own_type_hints(
+                    owner,
+                    getattr(sys.modules.get(owner.__module__, None), "__dict__", globalns),
+                    localns,
+                )
+                for owner in owners
+            }
+        except (NameError, AttributeError):
+            return None
+    return owners, hints_by_owner
+
+
+# ---------------------------------------------------------------------------
+# Deferred resolution
+# ---------------------------------------------------------------------------
+
+
+def flush_pending() -> None:
+    """Retry deferred classes until no additional annotations resolve.
+
+    A successful finalization can make another pending class resolvable, so this
+    function runs to a fixed point.  The field-registration finalizer is imported
+    lazily to keep this module focused on resolution and to avoid an import
+    cycle with :mod:`tvm_ffi.dataclasses.py_class`.
+    """
+    from .py_class import on_fields_resolved  # noqa: PLC0415
+
+    changed = True
+    while changed:
+        changed = False
+        remaining: list[_PendingClass] = []
+        for entry in _PENDING_CLASSES:
+            resolved = resolve_type_hints_by_owner(entry.cls, entry.globalns)
+            if resolved is None:
+                remaining.append(entry)
+            else:
+                on_fields_resolved(entry.type_info, resolved)
+                changed = True
+        _PENDING_CLASSES[:] = remaining

Review Comment:
   ![medium](https://www.gstatic.com/codereviewagent/medium-priority.svg)
   
   In the current implementation of `flush_pending`, if `on_fields_resolved` raises an exception for any of the pending classes, the loop is interrupted and `_PENDING_CLASSES` is left unmodified. This means that successfully resolved classes from the current iteration are not removed from `_PENDING_CLASSES`, and the failed class is also not rolled back or removed, leaving the global state inconsistent.
   
   We can make this robust by updating `_PENDING_CLASSES` in-place as we resolve each class, and wrapping the finalization in a `try...except` block to roll back the registration of the failed class if an error occurs.
   
   ```python
   def flush_pending() -> None:
       """Retry deferred classes until no additional annotations resolve.
   
       A successful finalization can make another pending class resolvable, so this
       function runs to a fixed point.  The field-registration finalizer is imported
       lazily to keep this module focused on resolution and to avoid an import
       cycle with :mod:`tvm_ffi.dataclasses.py_class`.
       """
       from .py_class import on_fields_resolved  # noqa: PLC0415
   
       changed = True
       while changed:
           changed = False
           i = 0
           while i < len(_PENDING_CLASSES):
               entry = _PENDING_CLASSES[i]
               resolved = resolve_type_hints_by_owner(entry.cls, entry.globalns)
               if resolved is not None:
                   _PENDING_CLASSES.pop(i)
                   try:
                       on_fields_resolved(entry.type_info, resolved)
                   except Exception:
                       rollback_registration(entry.cls, entry.type_info)
                       raise
                   changed = True
               else:
                   i += 1
   ```



##########
include/tvm/ffi/device.h:
##########
@@ -0,0 +1,155 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/*!
+ * \file tvm/ffi/device.h
+ * \brief Device handling.
+ */
+#ifndef TVM_FFI_DEVICE_H_
+#define TVM_FFI_DEVICE_H_
+
+#include <dlpack/dlpack.h>
+#include <tvm/ffi/string.h>
+#include <tvm/ffi/type_traits.h>
+
+#include <cstdint>
+#include <limits>
+#include <optional>
+#include <string>
+#include <string_view>
+
+namespace tvm {
+namespace ffi {
+namespace details {
+
+TVM_FFI_INLINE static std::optional<DLDeviceType> TryParseDLDeviceType(std::string_view name) {
+  if (name == "llvm" || name == "cpu" || name == "c" || name == "test") return kDLCPU;
+  if (name == "cuda" || name == "nvptx") return kDLCUDA;
+  if (name == "cl" || name == "opencl") return kDLOpenCL;
+  if (name == "vulkan") return kDLVulkan;
+  if (name == "metal") return kDLMetal;
+  if (name == "vpi") return kDLVPI;
+  if (name == "rocm") return kDLROCM;
+  if (name == "ext_dev") return kDLExtDev;
+  if (name == "hexagon") return kDLHexagon;
+  if (name == "webgpu") return kDLWebGPU;
+  if (name == "maia") return kDLMAIA;
+  if (name == "trn") return kDLTrn;
+  return std::nullopt;
+}
+
+TVM_FFI_INLINE static std::optional<int32_t> TryParseDLDeviceIndex(std::string_view index) {
+  if (index.empty()) return std::nullopt;
+  int64_t sign = 1;
+  size_t pos = 0;
+  if (index[0] == '-') {
+    sign = -1;
+    pos = 1;
+  }
+  if (pos >= index.size()) return std::nullopt;
+  int64_t value = 0;
+  for (; pos < index.size(); ++pos) {
+    char ch = index[pos];
+    if (ch < '0' || ch > '9') return std::nullopt;
+    value = value * 10 + (ch - '0');
+    if (value > std::numeric_limits<int32_t>::max()) return std::nullopt;
+  }
+  value *= sign;
+  if (value < std::numeric_limits<int32_t>::min() || value > std::numeric_limits<int32_t>::max()) {
+    return std::nullopt;
+  }
+  return static_cast<int32_t>(value);
+}

Review Comment:
   ![high](https://www.gstatic.com/codereviewagent/high-priority.svg)
   
   The current implementation of `TryParseDLDeviceIndex` has a bug when parsing the minimum possible `int32_t` value (`-2147483648`). Because the absolute value `2147483648` is checked against `std::numeric_limits<int32_t>::max()` (`2147483647`) inside the loop before the negative sign is applied, the function incorrectly returns `std::nullopt` for `-2147483648`.
   
   We can fix this by allowing the absolute value to reach `max() + 1` during the loop, and then validating the final signed value against the full `int32_t` range after applying the sign.
   
   ```c
   TVM_FFI_INLINE static std::optional<int32_t> TryParseDLDeviceIndex(std::string_view index) {
     if (index.empty()) return std::nullopt;
     int64_t sign = 1;
     size_t pos = 0;
     if (index[0] == '-') {
       sign = -1;
       pos = 1;
     }
     if (pos >= index.size()) return std::nullopt;
     int64_t value = 0;
     for (; pos < index.size(); ++pos) {
       char ch = index[pos];
       if (ch < '0' || ch > '9') return std::nullopt;
       value = value * 10 + (ch - '0');
       if (value > static_cast<int64_t>(std::numeric_limits<int32_t>::max()) + 1) return std::nullopt;
     }
     value *= sign;
     if (value < std::numeric_limits<int32_t>::min() || value > std::numeric_limits<int32_t>::max()) {
       return std::nullopt;
     }
     return static_cast<int32_t>(value);
   }
   ```



##########
python/tvm_ffi/dataclasses/py_class.py:
##########
@@ -521,24 +402,25 @@ def _register_fields_into_type(
     # ``tvm_ffi.dataclasses.fields()`` compat layer can recover defaults
     # and default_factory values.  _register_fields preserves order, so
     # own_fields and type_info.fields line up 1:1.
+    assert len(own_fields) == len(type_info.fields)
     for py_field, type_field in zip(own_fields, type_info.fields):
         type_field.dataclass_field = py_field

Review Comment:
   ![medium](https://www.gstatic.com/codereviewagent/medium-priority.svg)
   
   Since this codebase requires Python 3.10+, we can use `zip(..., strict=True)` instead of a separate `assert` statement. This ensures that a `ValueError` is raised if the lengths of `own_fields` and `type_info.fields` do not match, even when Python is run with optimizations disabled (which removes `assert` statements).
   
   ```suggestion
       for py_field, type_field in zip(own_fields, type_info.fields, strict=True):
           type_field.dataclass_field = py_field
   ```



##########
python/tvm_ffi/dataclasses/_resolve_fields.py:
##########
@@ -0,0 +1,462 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Forward-annotation resolution for ``@py_class`` registration.
+
+``@py_class`` registers a Python type before it resolves field annotations, so
+self-referential and mutually recursive annotations can refer to classes that
+are already present in the FFI type registry.  This module owns that early
+registration step, the per-module local namespace used by
+``typing.get_type_hints``, and the queue of classes whose annotations must be
+retried after later definitions become available.
+
+When a class is ready to finalize, this module lazily imports
+``py_class.on_fields_resolved``.  Keeping the finalizer import local preserves
+the boundary between annotation resolution and field registration while avoiding
+a top-level import cycle.
+"""
+
+from __future__ import annotations
+
+import sys
+import typing
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .. import core
+from .field import KW_ONLY
+
+if TYPE_CHECKING:
+    from ..core import TypeInfo
+else:
+    TypeInfo = Any
+
+ResolvedFields = tuple[list[type], dict[type, dict[str, Any]]]
+
+
+# ---------------------------------------------------------------------------
+# Module-level state
+# ---------------------------------------------------------------------------
+#
+# ``@py_class`` registration happens in two phases:
+#
+#   Phase 1 (register_type_without_fields)
+#       Allocates a C-level type index and inserts the class into the
+#       global type registry.  This must happen early so that self-
+#       referential and mutually-referential annotations can resolve
+#       the class via ``TypeSchema.from_annotation()``.  Phase 1 always
+#       succeeds or raises immediately for invalid parents.  Decorator
+#       options are stored by py_class.py on ``TypeInfo._decorator_args``.
+#
+#   Phase 2 (py_class.on_fields_resolved)
+#       Resolves string annotations via ``typing.get_type_hints``,
+#       returns per-owner resolved hints, and asks py_class.py to
+#       materialize ``Field`` objects, register fields/methods/type
+#       attributes with the Cython layer, and install dataclass dunders.
+#
+#       If ``get_type_hints`` raises ``NameError`` (forward reference
+#       not yet defined), the class is added to ``_PENDING_CLASSES``
+#       and retried after each successful phase-2.  If phase-2 fails
+#       for any other reason, ``rollback_registration`` undoes phase-1
+#       so the type key can be reused.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _PendingClass:
+    """Resolution state for a class waiting on unresolved annotations.
+
+    Only data needed to retry annotation resolution is stored here.  Decorator
+    options live on ``type_info._decorator_args`` so deferred and immediate
+    finalization use the same source of truth.
+    """
+
+    cls: type
+    type_info: TypeInfo
+    globalns: dict[str, Any]
+
+
+#: Classes whose phase-2 (field registration) was deferred because
+#: ``typing.get_type_hints`` raised ``NameError`` on an unresolved
+#: forward reference.  Retried after each successful phase-2 via
+#: :func:`flush_pending`.
+_PENDING_CLASSES: list[_PendingClass] = []
+
+#: Per-module mapping of ``class.__name__ → class`` for every
+#: ``@py_class``-decorated type.  Used as *localns* when resolving
+#: annotations so that mutual references between classes in the same
+#: module work even before the second class is assigned to the module
+#: variable by Python.
+_PY_CLASS_BY_MODULE: dict[str, dict[str, type]] = {}
+
+
+class _KWOnlyAnnotation:
+    """Type-valued stand-in accepted by ``typing.get_type_hints``."""
+
+
+def _is_kw_only_annotation(annotation: Any) -> bool:
+    if annotation is KW_ONLY or annotation is _KWOnlyAnnotation:
+        return True
+    if isinstance(annotation, str):
+        return annotation == "KW_ONLY" or annotation.endswith(".KW_ONLY")
+    forward_arg = getattr(annotation, "__forward_arg__", None)
+    if isinstance(forward_arg, str):
+        return forward_arg == "KW_ONLY" or forward_arg.endswith(".KW_ONLY")
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Phase 1: type registration
+# ---------------------------------------------------------------------------
+
+
+def _registered_type_info(cls: type) -> TypeInfo | None:
+    """Return the TypeInfo registered directly for *cls*, not inherited metadata."""
+    info = core._type_cls_to_type_info(cls)
+    if info is not None:
+        return info
+    return cls.__dict__.get("__tvm_ffi_type_info__", None)
+
+
+def register_type_without_fields(cls: type, type_key: str | None) -> TypeInfo:
+    """Register ``cls`` in the FFI type registry before resolving fields.
+
+    The returned :class:`~tvm_ffi.core.TypeInfo` has a type index, type key, and
+    Python class binding, but no field metadata yet.  This early registration is
+    what lets ``TypeSchema.from_annotation`` resolve references to ``cls`` while
+    the decorator is still running.
+
+    The class is also inserted into the module-local annotation namespace used
+    by :func:`resolve_type_hints_by_owner`, allowing sibling ``@py_class``
+    declarations in the same module to reference each other before the second
+    class has been assigned to the module global by Python.
+    """
+    parent_info = next(
+        (info for base in cls.__mro__[1:] if (info := _registered_type_info(base)) is not None),
+        None,
+    )
+    if parent_info is None:
+        raise TypeError(
+            f"{cls.__name__} must inherit from a registered FFI Object type (e.g. tvm_ffi.Object)"
+        )
+    if type_key is None:
+        type_key = f"{cls.__module__}.{cls.__qualname__}"
+    info = core._register_py_class(parent_info, type_key, cls)
+    setattr(cls, "__tvm_ffi_type_info__", info)
+    # Register in resolution namespace so sibling classes can find us.
+    _PY_CLASS_BY_MODULE.setdefault(cls.__module__, {})[cls.__name__] = cls
+    return info
+
+
+def rollback_registration(cls: type, type_info: TypeInfo) -> None:
+    """Undo Python-side state from :func:`register_type_without_fields`.
+
+    The C-level type index is permanently consumed (cannot be reclaimed),
+    but the Python-level registry dicts are cleaned up so a retry with
+    the same type key does not hit "already registered".  The dataclass marker
+    is also removed because failed phase-2 finalization means the class is not a
+    usable FFI dataclass.
+    """
+    # Remove from the Cython-level registry dicts (TYPE_KEY_TO_INFO,
+    # TYPE_CLS_TO_INFO, TYPE_INDEX_TO_INFO, TYPE_INDEX_TO_CLS).
+    core._rollback_py_class(type_info)  # ty: ignore[unresolved-attribute]
+    # Remove from our own module-level resolution namespace.
+    _PY_CLASS_BY_MODULE.get(cls.__module__, {}).pop(cls.__name__, None)
+    for attr in ("__tvm_ffi_type_info__", "__ffi_is_dataclass__"):
+        try:
+            delattr(cls, attr)
+        except AttributeError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Annotation resolution
+# ---------------------------------------------------------------------------
+
+
+def own_annotations(cls: type) -> dict[str, Any]:
+    """Return annotations declared directly on ``cls`` without MRO merging."""
+    # Python 3.14+ (PEP 749): annotations are lazily evaluated via
+    # __annotate__ and no longer stored directly in __dict__.  getattr()
+    # triggers evaluation and returns per-class annotations correctly.
+    # On Python < 3.14, getattr() follows MRO and returns *parent*
+    # annotations when the child has none — use __dict__ to avoid that.
+    if sys.version_info >= (3, 14):
+        return getattr(cls, "__annotations__", {})
+    return cls.__dict__.get("__annotations__", {})
+
+
+def _field_owner_classes(cls: type) -> list[type]:
+    """Return local MRO entries whose annotations become fields on ``cls``.
+
+    A Python subclass of a registered FFI parent may include unregistered mixin
+    bases before the registered parent.  Those mixin annotations are owned by
+    the new Python type and should be registered together with ``cls``.  Fields
+    already represented by the nearest registered parent are excluded.
+    """
+    registered_parent = next(
+        (b for b in cls.__mro__[1:] if _registered_type_info(b) is not None), object
+    )
+    represented = set(registered_parent.__mro__)
+    return [
+        b
+        for b in reversed(cls.__mro__)
+        if b is not object and b not in represented and own_annotations(b)
+    ]
+
+
+def _build_localns(cls: type, *, cross_module: bool = False) -> dict[str, Any]:
+    """Build the localns dict for resolving ``cls``'s annotations.
+
+    By default, includes only classes from ``cls.__module__``, preserving
+    standard Python name resolution semantics.  When ``cross_module=True``,
+    also includes classes from all other registered modules as a fallback
+    — this is needed when ``cls`` has a forward reference to a class in
+    another module that can't appear in ``cls.__module__``'s globals due
+    to a circular import (e.g. the target is imported only under
+    ``if TYPE_CHECKING:``).
+
+    Cross-module entries are added with ``setdefault`` so same-module
+    classes and the class itself always take precedence over foreign
+    classes with the same ``__name__``.
+    """
+    localns = dict(_PY_CLASS_BY_MODULE.get(cls.__module__, {}))
+    localns[cls.__name__] = cls
+    if cross_module:
+        for mod_name, mod_classes in list(_PY_CLASS_BY_MODULE.items()):
+            if mod_name == cls.__module__:
+                continue
+            for name, klass in mod_classes.items():
+                localns.setdefault(name, klass)
+    return localns
+
+
+def _resolve_own_type_hints(
+    owner: type,
+    globalns: dict[str, Any],
+    localns: dict[str, Any],
+) -> dict[str, Any]:
+    """Resolve only annotations declared directly on ``owner``.
+
+    ``typing.get_type_hints(cls)`` merges annotations across the full MRO.
+    That is wrong for py_class phase 2 because inherited C++/c_class fields
+    are already registered by the parent type.  Resolving only the owner
+    annotations also avoids evaluating parent annotations in the child
+    module's namespace.
+
+    Python 3.10's ``typing.get_type_hints`` rejects ``dataclasses.KW_ONLY``
+    because it is a singleton, not a type.  Replace it in the temporary shim
+    annotations, then restore it in the resolved hints.
+    """
+    annotations = own_annotations(owner)
+    if not annotations:
+        return {}
+    shim_annotations = dict(annotations)
+    kw_only_names: list[str] = []
+    for name, annotation in annotations.items():
+        if _is_kw_only_annotation(annotation):
+            shim_annotations[name] = _KWOnlyAnnotation
+            kw_only_names.append(name)
+    shim = type(
+        f"_{owner.__name__}OwnAnnotations",
+        (),
+        {"__annotations__": shim_annotations, "__module__": owner.__module__},
+    )
+    kwargs: dict[str, Any] = {"globalns": globalns, "localns": localns}
+    if sys.version_info >= (3, 11):
+        kwargs["include_extras"] = True
+    hints = typing.get_type_hints(shim, **kwargs)
+    for name in kw_only_names:
+        hints[name] = KW_ONLY
+    return hints
+
+
+def resolve_type_hints_by_owner(
+    cls: type,
+    globalns: dict[str, Any],
+) -> ResolvedFields | None:
+    """Resolve field annotations grouped by owner class.
+
+    Returns ``(owners, hints_by_owner)`` when every annotation can be resolved.
+    Returns :data:`None` when a forward reference is still unavailable, signaling
+    that the caller should defer field registration and retry later.
+    """
+    # Resolve string annotations to types; return None (defer) on NameError.
+    #
+    # First try with module-scoped localns (standard Python name resolution).
+    # On NameError, retry with a cross-module localns that includes classes
+    # from every registered module — this handles circular imports where the
+    # target of a forward reference is imported only under TYPE_CHECKING and
+    # therefore never enters the declaring module's globals.
+    owners = _field_owner_classes(cls)
+    localns = _build_localns(cls)
+    localns.update({owner.__name__: owner for owner in owners})
+    try:
+        hints_by_owner = {
+            owner: _resolve_own_type_hints(
+                owner,
+                getattr(sys.modules.get(owner.__module__, None), "__dict__", globalns),
+                localns,
+            )
+            for owner in owners
+        }
+    except (NameError, AttributeError):
+        localns = _build_localns(cls, cross_module=True)
+        localns.update({owner.__name__: owner for owner in owners})
+        try:
+            hints_by_owner = {
+                owner: _resolve_own_type_hints(
+                    owner,
+                    getattr(sys.modules.get(owner.__module__, None), "__dict__", globalns),
+                    localns,
+                )
+                for owner in owners
+            }
+        except (NameError, AttributeError):
+            return None
+    return owners, hints_by_owner
+
+
+# ---------------------------------------------------------------------------
+# Deferred resolution
+# ---------------------------------------------------------------------------
+
+
+def flush_pending() -> None:
+    """Retry deferred classes until no additional annotations resolve.
+
+    A successful finalization can make another pending class resolvable, so this
+    function runs to a fixed point.  The field-registration finalizer is imported
+    lazily to keep this module focused on resolution and to avoid an import
+    cycle with :mod:`tvm_ffi.dataclasses.py_class`.
+    """
+    from .py_class import on_fields_resolved  # noqa: PLC0415
+
+    changed = True
+    while changed:
+        changed = False
+        remaining: list[_PendingClass] = []
+        for entry in _PENDING_CLASSES:
+            resolved = resolve_type_hints_by_owner(entry.cls, entry.globalns)
+            if resolved is None:
+                remaining.append(entry)
+            else:
+                on_fields_resolved(entry.type_info, resolved)
+                changed = True
+        _PENDING_CLASSES[:] = remaining
+
+
+def _raise_unresolved_forward_reference(cls: type, globalns: dict[str, Any]) -> None:
+    """Raise :class:`TypeError` listing the annotations that cannot be resolved."""
+    localns = _build_localns(cls, cross_module=True)
+    owners = _field_owner_classes(cls)
+    localns.update({owner.__name__: owner for owner in owners})
+    unresolved: list[str] = []
+    for owner in owners:
+        for name, ann_str in own_annotations(owner).items():
+            if isinstance(ann_str, str):
+                try:
+                    eval(ann_str, globalns, localns)  # pylint: disable=eval-used
+                except (NameError, AttributeError) as err:
+                    unresolved.append(f"{name}: {ann_str} ({err})")

Review Comment:
   ![medium](https://www.gstatic.com/codereviewagent/medium-priority.svg)
   
   When diagnosing unresolved forward references, `eval` is used to check which annotations are failing. However, evaluating arbitrary annotation strings can raise exceptions other than `NameError` or `AttributeError` (such as `SyntaxError`, `TypeError`, or `ValueError`). Catching `Exception` ensures that any evaluation failure is gracefully captured and reported in the final `TypeError` message rather than crashing the diagnostic routine itself.
   
   ```suggestion
                   try:
                       eval(ann_str, globalns, localns)  # pylint: disable=eval-used
                   except Exception as err:
                       unresolved.append(f"{name}: {ann_str} ({err})")
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3575928856


##########
include/tvm/ffi/reflection/registry.h:
##########
@@ -1004,16 +1104,32 @@ class TypeAttrDef : public ReflectionDefBase {
    *
    * \return The TypeAttrDef object.
    */
-  template <typename Func>
+  template <typename Func, std::enable_if_t<!std::is_convertible_v<Func&&, AnyView> &&
+                                                !std::is_convertible_v<std::decay_t<Func>, AnyView>,
+                                            int> = 0>
   TypeAttrDef& def(const char* name, Func&& func) {
-    TVMFFIByteArray name_array = {name, std::char_traits<char>::length(name)};
     ffi::Function ffi_func =
         GetMethod(std::string(type_key_) + "." + name, std::forward<Func>(func));
-    TVMFFIAny value_any = AnyView(ffi_func).CopyToTVMFFIAny();
-    TVM_FFI_CHECK_SAFE_CALL(TVMFFITypeRegisterAttr(type_index_, &name_array, &value_any));
+    RegisterTypeAttrValue(type_index_, name, ffi_func);
     return *this;
   }
 
+  /*!
+   * \brief Register the standard AnyView conversion type attribute.
+   *
+   * \tparam TSelf The type produced by the conversion.
+   *
+   * \return The TypeAttrDef object.
+   */
+  template <typename TSelf>
+  TVM_FFI_INLINE TypeAttrDef& def_convert() {
+    if constexpr (details::HasContainerType<TSelf>::value) {
+      static_assert(std::is_same_v<typename TSelf::ContainerType, Class>,
+                    "TSelf::ContainerType must match TypeAttrDef's object type");
+    }
+    return def(type_attr::kConvert, &details::FFIConvertFromAnyViewToObjectRef<TSelf>);

Review Comment:
   Thanks for the suggestion. I would like to keep `def_convert`: this is expected to be a common registration for asymmetric conversions, where the reflected object type and the returned public reference type differ. The helper gives that pattern a named API, avoids repeating the `kConvert`/`FFIConvertFromAnyViewToObjectRef` wiring at every call site, and retains the compile-time `ContainerType` consistency check when available. I am therefore keeping the helper rather than expanding each registration into the generic one-liner.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "tqchen (via GitHub)" <gi...@apache.org>.
tqchen commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3576232313


##########
python/tvm_ffi/utils/descriptors.py:
##########
@@ -0,0 +1,80 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Descriptor utilities for the tvm_ffi Python package."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from typing import Any, Callable, Generic, TypeVar, overload
+
+_T = TypeVar("_T")
+
+
+def _get_forward_annotations(obj: Any) -> dict[str, Any]:
+    """Return Python 3.14+ annotations without forcing unresolved names."""
+    annotationlib: Any = importlib.import_module("annotationlib")
+    return annotationlib.get_annotations(obj, format=annotationlib.Format.FORWARDREF)
+
+
+class init_property(Generic[_T]):
+    """Auto-registered C++ field with eager computation at ``__init__`` time.

Review Comment:
   this seems should belong to dataclass category as utils is generic thing that do not depend on tvm ffi constructs like filelock



##########
tests/cpp/test_device.cc:
##########
@@ -0,0 +1,60 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+#include <gtest/gtest.h>
+#include <tvm/ffi/any.h>
+#include <tvm/ffi/device.h>
+
+namespace {
+
+using namespace tvm::ffi;
+
+TEST(Device, AnyConversion) {
+  DLDevice device{kDLCUDA, 1};
+  AnyView view = device;
+
+  DLDevice converted = view.cast<DLDevice>();
+  EXPECT_EQ(converted.device_type, kDLCUDA);
+  EXPECT_EQ(converted.device_id, 1);
+}
+
+TEST(Device, AnyConversionWithString) {
+  AnyView cpu_view = "cpu";
+  DLDevice cpu = cpu_view.cast<DLDevice>();
+  EXPECT_EQ(cpu.device_type, kDLCPU);
+  EXPECT_EQ(cpu.device_id, 0);
+
+  Any cuda_any = String("cuda:3");
+  DLDevice cuda = cuda_any.cast<DLDevice>();
+  EXPECT_EQ(cuda.device_type, kDLCUDA);
+  EXPECT_EQ(cuda.device_id, 3);
+
+  AnyView opencl_view = "opencl:-2";

Review Comment:
   is negative value allowed? i think we should reject negative value? also simplifies parser



##########
include/tvm/ffi/device.h:
##########
@@ -0,0 +1,155 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/*!
+ * \file tvm/ffi/device.h
+ * \brief Device handling.
+ */
+#ifndef TVM_FFI_DEVICE_H_
+#define TVM_FFI_DEVICE_H_
+
+#include <dlpack/dlpack.h>
+#include <tvm/ffi/string.h>
+#include <tvm/ffi/type_traits.h>
+
+#include <cstdint>
+#include <limits>
+#include <optional>
+#include <string>
+#include <string_view>
+
+namespace tvm {
+namespace ffi {
+namespace details {
+
+TVM_FFI_INLINE static std::optional<DLDeviceType> TryParseDLDeviceType(std::string_view name) {
+  if (name == "llvm" || name == "cpu" || name == "c" || name == "test") return kDLCPU;

Review Comment:
   i know that we had some broad translation on python side which tries to be compact with some compiler target, as part of core i think it does not makes sense likely, let us only keep cpu, cuda, opencl here.
   
   i will followup with downstream changes so they do not directly rely on target name like llvm maps to cpu



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#issuecomment-4965400930

   /gemini review


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "tqchen (via GitHub)" <gi...@apache.org>.
tqchen commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3575739786


##########
include/tvm/ffi/type_traits.h:
##########
@@ -536,6 +537,88 @@ struct TypeTraits<void*> : public TypeTraitsBase {
   }
 };
 
+namespace details {
+
+TVM_FFI_INLINE static std::optional<std::string_view> TryGetStringViewFromAny(
+    const TVMFFIAny* src) {
+  if (src->type_index == TypeIndex::kTVMFFIRawStr) {
+    return std::string_view(src->v_c_str);
+  }
+  if (src->type_index == TypeIndex::kTVMFFISmallStr) {
+    TVMFFIByteArray bytes = TVMFFISmallBytesGetContentByteArray(src);
+    return std::string_view(bytes.data, bytes.size);
+  }
+  if (src->type_index == TypeIndex::kTVMFFIStr) {
+    TVMFFIByteArray* bytes = TVMFFIBytesGetByteArrayPtr(src->v_obj);
+    return std::string_view(bytes->data, bytes->size);
+  }
+  return std::nullopt;
+}
+
+TVM_FFI_INLINE static std::optional<DLDeviceType> TryParseDLDeviceType(std::string_view name) {
+  if (name == "llvm" || name == "cpu" || name == "c" || name == "test") return kDLCPU;
+  if (name == "cuda" || name == "nvptx") return kDLCUDA;
+  if (name == "cl" || name == "opencl") return kDLOpenCL;
+  if (name == "vulkan") return kDLVulkan;
+  if (name == "metal") return kDLMetal;
+  if (name == "vpi") return kDLVPI;
+  if (name == "rocm") return kDLROCM;
+  if (name == "ext_dev") return kDLExtDev;
+  if (name == "hexagon") return kDLHexagon;
+  if (name == "webgpu") return kDLWebGPU;
+  if (name == "maia") return kDLMAIA;
+  if (name == "trn") return kDLTrn;
+  return std::nullopt;
+}
+
+TVM_FFI_INLINE static std::optional<int32_t> TryParseDLDeviceIndex(std::string_view index) {
+  if (index.empty()) return std::nullopt;
+  int64_t sign = 1;
+  size_t pos = 0;
+  if (index[0] == '-') {
+    sign = -1;
+    pos = 1;
+  }
+  if (pos >= index.size()) return std::nullopt;
+  int64_t value = 0;
+  for (; pos < index.size(); ++pos) {
+    char ch = index[pos];
+    if (ch < '0' || ch > '9') return std::nullopt;
+    value = value * 10 + (ch - '0');
+    if (value > std::numeric_limits<int32_t>::max()) return std::nullopt;
+  }
+  value *= sign;
+  if (value < std::numeric_limits<int32_t>::min() || value > std::numeric_limits<int32_t>::max()) {
+    return std::nullopt;
+  }
+  return static_cast<int32_t>(value);
+}
+
+TVM_FFI_INLINE static std::optional<DLDevice> TryStringViewToDLDevice(std::string_view str) {
+  size_t space_pos = str.find(' ');
+  if (space_pos != std::string_view::npos) {
+    str = str.substr(0, space_pos);
+  }
+  size_t colon_pos = str.find(':');
+  std::string_view name = colon_pos == std::string_view::npos ? str : str.substr(0, colon_pos);
+  if (name.empty()) return std::nullopt;
+  if (str.find(':', colon_pos == std::string_view::npos ? str.size() : colon_pos + 1) !=
+      std::string_view::npos) {
+    return std::nullopt;
+  }
+  std::optional<DLDeviceType> device_type = TryParseDLDeviceType(name);

Review Comment:
   now that we do string handling perhaps worthadding ffi/device.h like dtype.h



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "gemini-code-assist[bot] (via GitHub)" <gi...@apache.org>.
gemini-code-assist[bot] commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3574212180


##########
python/tvm_ffi/_dunder.py:
##########
@@ -104,6 +114,22 @@ def __init__(self: Any, *args: Any, **kwargs: Any) -> None:
     return __init__
 
 
+def _collect_init_property_funcs(type_cls: type) -> list[tuple[str, Callable[..., Any]]]:
+    """Collect ``(name, func)`` pairs for all ``init_property`` fields in MRO order.
+
+    Walks from the most specific class toward the root.  Child definitions take
+    precedence over parent definitions of the same name (first-seen wins).
+    """
+    funcs: list[tuple[str, Callable[..., Any]]] = []
+    seen: set[str] = set()
+    for cls in type_cls.__mro__:
+        for name, func in cls.__dict__.get("__ffi_init_property_funcs__", {}).items():
+            if name not in seen:
+                funcs.append((name, func))
+                seen.add(name)
+    return funcs

Review Comment:
   ![high](https://www.gstatic.com/codereviewagent/high-priority.svg)
   
   In `_collect_init_property_funcs`, walking the MRO from child to parent (most specific to least specific) means child properties are evaluated before parent properties. If a child's `init_property` depends on a parent's `init_property` (or parent fields), it will be evaluated with uninitialized/default values. Walking the MRO in reverse (from root to child) using a dictionary ensures parent properties are evaluated first, while still allowing child definitions to correctly override parent definitions of the same name.
   
   ```python
   def _collect_init_property_funcs(type_cls: type) -> list[tuple[str, Callable[..., Any]]]:
       """Collect (name, func) pairs for all init_property fields in MRO order.
   
       Walks from the root toward the most specific class so that parent properties
       are evaluated before child properties (allowing dependent properties to work).
       Child definitions override parent definitions of the same name.
       """
       funcs_dict: dict[str, Callable[..., Any]] = {}
       for cls in reversed(type_cls.__mro__):
           for name, func in cls.__dict__.get("__ffi_init_property_funcs__", {}).items():
               funcs_dict[name] = func
       return list(funcs_dict.items())
   ```



##########
python/tvm_ffi/utils/descriptors.py:
##########
@@ -0,0 +1,61 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Descriptor utilities for the tvm_ffi Python package."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Generic, TypeVar, overload
+
+_T = TypeVar("_T")
+
+
+class init_property(Generic[_T]):
+    """Auto-registered C++ field with eager computation at ``__init__`` time.
+
+    ``@py_class`` detects ``init_property`` descriptors and registers each one
+    as ``field(init=False, structural_eq="ignore")``, so the computed value
+    lives in C++ object storage and is accessible cross-language.  The value
+    is computed once — immediately after ``__ffi_init__`` — and stored via the
+    field's C++ slot.  Subsequent reads go directly to C++ memory.
+
+    The return annotation of the decorated function is injected into the class
+    ``__annotations__`` during class body execution so the field resolution
+    machinery picks it up automatically.  If no return annotation is present,
+    ``typing.Any`` is used.
+    """
+
+    def __init__(self, func: Callable[[Any], _T]) -> None:
+        self.func = func
+        self.name: str | None = None
+        self._return_annotation: Any = func.__annotations__.get("return")
+
+    @overload
+    def __get__(self, obj: None, objtype: type) -> init_property[_T]: ...
+    @overload
+    def __get__(self, obj: object, objtype: type) -> _T: ...
+    def __get__(self, obj: object | None, objtype: type) -> _T | init_property[_T]:
+        return self
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self.name = name
+
+        ann = self._return_annotation if self._return_annotation is not None else Any
+        # Inject into the owner's own __annotations__ so on_fields_resolved
+        # processes this name as a typed field.
+        if "__annotations__" not in owner.__dict__:
+            owner.__annotations__ = {}
+        owner.__annotations__[name] = ann

Review Comment:
   ![high](https://www.gstatic.com/codereviewagent/high-priority.svg)
   
   In Python 3.14+ (PEP 749), `__annotations__` is a descriptor on the class that lazily evaluates annotations via `__annotate__`. Assigning `owner.__annotations__ = {}` replaces this descriptor with a plain dictionary, which completely shadows and loses any other annotations declared on the class. Since `__annotations__` is no longer inherited in Python 3.14+, we can safely mutate the dictionary returned by `owner.__annotations__` directly without affecting parent classes, preserving other annotations.
   
   ```suggestion
           import sys
   
           ann = self._return_annotation if self._return_annotation is not None else Any
           # Inject into the owner's own __annotations__ so on_fields_resolved
           # processes this name as a typed field.
           if sys.version_info >= (3, 14):
               owner.__annotations__[name] = ann
           else:
               if "__annotations__" not in owner.__dict__:
                   owner.__annotations__ = {}
               owner.__annotations__[name] = ann
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3576162650


##########
python/tvm_ffi/dataclasses/_resolve_fields.py:
##########
@@ -0,0 +1,462 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Forward-annotation resolution for ``@py_class`` registration.
+
+``@py_class`` registers a Python type before it resolves field annotations, so
+self-referential and mutually recursive annotations can refer to classes that
+are already present in the FFI type registry.  This module owns that early
+registration step, the per-module local namespace used by
+``typing.get_type_hints``, and the queue of classes whose annotations must be
+retried after later definitions become available.
+
+When a class is ready to finalize, this module lazily imports
+``py_class.on_fields_resolved``.  Keeping the finalizer import local preserves
+the boundary between annotation resolution and field registration while avoiding
+a top-level import cycle.
+"""
+
+from __future__ import annotations
+
+import sys
+import typing
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .. import core
+from .field import KW_ONLY
+
+if TYPE_CHECKING:
+    from ..core import TypeInfo
+else:
+    TypeInfo = Any
+
+ResolvedFields = tuple[list[type], dict[type, dict[str, Any]]]
+
+
+# ---------------------------------------------------------------------------
+# Module-level state
+# ---------------------------------------------------------------------------
+#
+# ``@py_class`` registration happens in two phases:
+#
+#   Phase 1 (register_type_without_fields)
+#       Allocates a C-level type index and inserts the class into the
+#       global type registry.  This must happen early so that self-
+#       referential and mutually-referential annotations can resolve
+#       the class via ``TypeSchema.from_annotation()``.  Phase 1 always
+#       succeeds or raises immediately for invalid parents.  Decorator
+#       options are stored by py_class.py on ``TypeInfo._decorator_args``.
+#
+#   Phase 2 (py_class.on_fields_resolved)
+#       Resolves string annotations via ``typing.get_type_hints``,
+#       returns per-owner resolved hints, and asks py_class.py to
+#       materialize ``Field`` objects, register fields/methods/type
+#       attributes with the Cython layer, and install dataclass dunders.
+#
+#       If ``get_type_hints`` raises ``NameError`` (forward reference
+#       not yet defined), the class is added to ``_PENDING_CLASSES``
+#       and retried after each successful phase-2.  If phase-2 fails
+#       for any other reason, ``rollback_registration`` undoes phase-1
+#       so the type key can be reused.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _PendingClass:
+    """Resolution state for a class waiting on unresolved annotations.
+
+    Only data needed to retry annotation resolution is stored here.  Decorator
+    options live on ``type_info._decorator_args`` so deferred and immediate
+    finalization use the same source of truth.
+    """
+
+    cls: type
+    type_info: TypeInfo
+    globalns: dict[str, Any]
+
+
+#: Classes whose phase-2 (field registration) was deferred because
+#: ``typing.get_type_hints`` raised ``NameError`` on an unresolved
+#: forward reference.  Retried after each successful phase-2 via
+#: :func:`flush_pending`.
+_PENDING_CLASSES: list[_PendingClass] = []
+
+#: Per-module mapping of ``class.__name__ → class`` for every
+#: ``@py_class``-decorated type.  Used as *localns* when resolving
+#: annotations so that mutual references between classes in the same
+#: module work even before the second class is assigned to the module
+#: variable by Python.
+_PY_CLASS_BY_MODULE: dict[str, dict[str, type]] = {}
+
+
+class _KWOnlyAnnotation:
+    """Type-valued stand-in accepted by ``typing.get_type_hints``."""
+
+
+def _is_kw_only_annotation(annotation: Any) -> bool:
+    if annotation is KW_ONLY or annotation is _KWOnlyAnnotation:
+        return True
+    if isinstance(annotation, str):
+        return annotation == "KW_ONLY" or annotation.endswith(".KW_ONLY")
+    forward_arg = getattr(annotation, "__forward_arg__", None)
+    if isinstance(forward_arg, str):
+        return forward_arg == "KW_ONLY" or forward_arg.endswith(".KW_ONLY")
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Phase 1: type registration
+# ---------------------------------------------------------------------------
+
+
+def _registered_type_info(cls: type) -> TypeInfo | None:
+    """Return the TypeInfo registered directly for *cls*, not inherited metadata."""
+    info = core._type_cls_to_type_info(cls)
+    if info is not None:
+        return info
+    return cls.__dict__.get("__tvm_ffi_type_info__", None)
+
+
+def register_type_without_fields(cls: type, type_key: str | None) -> TypeInfo:
+    """Register ``cls`` in the FFI type registry before resolving fields.
+
+    The returned :class:`~tvm_ffi.core.TypeInfo` has a type index, type key, and
+    Python class binding, but no field metadata yet.  This early registration is
+    what lets ``TypeSchema.from_annotation`` resolve references to ``cls`` while
+    the decorator is still running.
+
+    The class is also inserted into the module-local annotation namespace used
+    by :func:`resolve_type_hints_by_owner`, allowing sibling ``@py_class``
+    declarations in the same module to reference each other before the second
+    class has been assigned to the module global by Python.
+    """
+    parent_info = next(
+        (info for base in cls.__mro__[1:] if (info := _registered_type_info(base)) is not None),
+        None,
+    )
+    if parent_info is None:
+        raise TypeError(
+            f"{cls.__name__} must inherit from a registered FFI Object type (e.g. tvm_ffi.Object)"
+        )
+    if type_key is None:
+        type_key = f"{cls.__module__}.{cls.__qualname__}"
+    info = core._register_py_class(parent_info, type_key, cls)
+    setattr(cls, "__tvm_ffi_type_info__", info)
+    # Register in resolution namespace so sibling classes can find us.
+    _PY_CLASS_BY_MODULE.setdefault(cls.__module__, {})[cls.__name__] = cls
+    return info
+
+
+def rollback_registration(cls: type, type_info: TypeInfo) -> None:
+    """Undo Python-side state from :func:`register_type_without_fields`.
+
+    The C-level type index is permanently consumed (cannot be reclaimed),
+    but the Python-level registry dicts are cleaned up so a retry with
+    the same type key does not hit "already registered".  The dataclass marker
+    is also removed because failed phase-2 finalization means the class is not a
+    usable FFI dataclass.
+    """
+    # Remove from the Cython-level registry dicts (TYPE_KEY_TO_INFO,
+    # TYPE_CLS_TO_INFO, TYPE_INDEX_TO_INFO, TYPE_INDEX_TO_CLS).
+    core._rollback_py_class(type_info)  # ty: ignore[unresolved-attribute]
+    # Remove from our own module-level resolution namespace.
+    _PY_CLASS_BY_MODULE.get(cls.__module__, {}).pop(cls.__name__, None)
+    for attr in ("__tvm_ffi_type_info__", "__ffi_is_dataclass__"):
+        try:
+            delattr(cls, attr)
+        except AttributeError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Annotation resolution
+# ---------------------------------------------------------------------------
+
+
+def own_annotations(cls: type) -> dict[str, Any]:
+    """Return annotations declared directly on ``cls`` without MRO merging."""
+    # Python 3.14+ (PEP 749): annotations are lazily evaluated via
+    # __annotate__ and no longer stored directly in __dict__.  getattr()
+    # triggers evaluation and returns per-class annotations correctly.
+    # On Python < 3.14, getattr() follows MRO and returns *parent*
+    # annotations when the child has none — use __dict__ to avoid that.
+    if sys.version_info >= (3, 14):
+        return getattr(cls, "__annotations__", {})
+    return cls.__dict__.get("__annotations__", {})
+
+
+def _field_owner_classes(cls: type) -> list[type]:
+    """Return local MRO entries whose annotations become fields on ``cls``.
+
+    A Python subclass of a registered FFI parent may include unregistered mixin
+    bases before the registered parent.  Those mixin annotations are owned by
+    the new Python type and should be registered together with ``cls``.  Fields
+    already represented by the nearest registered parent are excluded.
+    """
+    registered_parent = next(
+        (b for b in cls.__mro__[1:] if _registered_type_info(b) is not None), object
+    )
+    represented = set(registered_parent.__mro__)
+    return [
+        b
+        for b in reversed(cls.__mro__)
+        if b is not object and b not in represented and own_annotations(b)
+    ]
+
+
+def _build_localns(cls: type, *, cross_module: bool = False) -> dict[str, Any]:
+    """Build the localns dict for resolving ``cls``'s annotations.
+
+    By default, includes only classes from ``cls.__module__``, preserving
+    standard Python name resolution semantics.  When ``cross_module=True``,
+    also includes classes from all other registered modules as a fallback
+    — this is needed when ``cls`` has a forward reference to a class in
+    another module that can't appear in ``cls.__module__``'s globals due
+    to a circular import (e.g. the target is imported only under
+    ``if TYPE_CHECKING:``).
+
+    Cross-module entries are added with ``setdefault`` so same-module
+    classes and the class itself always take precedence over foreign
+    classes with the same ``__name__``.
+    """
+    localns = dict(_PY_CLASS_BY_MODULE.get(cls.__module__, {}))
+    localns[cls.__name__] = cls
+    if cross_module:
+        for mod_name, mod_classes in list(_PY_CLASS_BY_MODULE.items()):
+            if mod_name == cls.__module__:
+                continue
+            for name, klass in mod_classes.items():
+                localns.setdefault(name, klass)
+    return localns
+
+
+def _resolve_own_type_hints(
+    owner: type,
+    globalns: dict[str, Any],
+    localns: dict[str, Any],
+) -> dict[str, Any]:
+    """Resolve only annotations declared directly on ``owner``.
+
+    ``typing.get_type_hints(cls)`` merges annotations across the full MRO.
+    That is wrong for py_class phase 2 because inherited C++/c_class fields
+    are already registered by the parent type.  Resolving only the owner
+    annotations also avoids evaluating parent annotations in the child
+    module's namespace.
+
+    Python 3.10's ``typing.get_type_hints`` rejects ``dataclasses.KW_ONLY``
+    because it is a singleton, not a type.  Replace it in the temporary shim
+    annotations, then restore it in the resolved hints.
+    """
+    annotations = own_annotations(owner)
+    if not annotations:
+        return {}
+    shim_annotations = dict(annotations)
+    kw_only_names: list[str] = []
+    for name, annotation in annotations.items():
+        if _is_kw_only_annotation(annotation):
+            shim_annotations[name] = _KWOnlyAnnotation
+            kw_only_names.append(name)
+    shim = type(
+        f"_{owner.__name__}OwnAnnotations",
+        (),
+        {"__annotations__": shim_annotations, "__module__": owner.__module__},
+    )
+    kwargs: dict[str, Any] = {"globalns": globalns, "localns": localns}
+    if sys.version_info >= (3, 11):
+        kwargs["include_extras"] = True
+    hints = typing.get_type_hints(shim, **kwargs)
+    for name in kw_only_names:
+        hints[name] = KW_ONLY
+    return hints
+
+
+def resolve_type_hints_by_owner(
+    cls: type,
+    globalns: dict[str, Any],
+) -> ResolvedFields | None:
+    """Resolve field annotations grouped by owner class.
+
+    Returns ``(owners, hints_by_owner)`` when every annotation can be resolved.
+    Returns :data:`None` when a forward reference is still unavailable, signaling
+    that the caller should defer field registration and retry later.
+    """
+    # Resolve string annotations to types; return None (defer) on NameError.
+    #
+    # First try with module-scoped localns (standard Python name resolution).
+    # On NameError, retry with a cross-module localns that includes classes
+    # from every registered module — this handles circular imports where the
+    # target of a forward reference is imported only under TYPE_CHECKING and
+    # therefore never enters the declaring module's globals.
+    owners = _field_owner_classes(cls)
+    localns = _build_localns(cls)
+    localns.update({owner.__name__: owner for owner in owners})
+    try:
+        hints_by_owner = {
+            owner: _resolve_own_type_hints(
+                owner,
+                getattr(sys.modules.get(owner.__module__, None), "__dict__", globalns),
+                localns,
+            )
+            for owner in owners
+        }
+    except (NameError, AttributeError):
+        localns = _build_localns(cls, cross_module=True)
+        localns.update({owner.__name__: owner for owner in owners})
+        try:
+            hints_by_owner = {
+                owner: _resolve_own_type_hints(
+                    owner,
+                    getattr(sys.modules.get(owner.__module__, None), "__dict__", globalns),
+                    localns,
+                )
+                for owner in owners
+            }
+        except (NameError, AttributeError):
+            return None
+    return owners, hints_by_owner
+
+
+# ---------------------------------------------------------------------------
+# Deferred resolution
+# ---------------------------------------------------------------------------
+
+
+def flush_pending() -> None:
+    """Retry deferred classes until no additional annotations resolve.
+
+    A successful finalization can make another pending class resolvable, so this
+    function runs to a fixed point.  The field-registration finalizer is imported
+    lazily to keep this module focused on resolution and to avoid an import
+    cycle with :mod:`tvm_ffi.dataclasses.py_class`.
+    """
+    from .py_class import on_fields_resolved  # noqa: PLC0415
+
+    changed = True
+    while changed:
+        changed = False
+        remaining: list[_PendingClass] = []
+        for entry in _PENDING_CLASSES:
+            resolved = resolve_type_hints_by_owner(entry.cls, entry.globalns)
+            if resolved is None:
+                remaining.append(entry)
+            else:
+                on_fields_resolved(entry.type_info, resolved)
+                changed = True
+        _PENDING_CLASSES[:] = remaining
+
+
+def _raise_unresolved_forward_reference(cls: type, globalns: dict[str, Any]) -> None:
+    """Raise :class:`TypeError` listing the annotations that cannot be resolved."""
+    localns = _build_localns(cls, cross_module=True)
+    owners = _field_owner_classes(cls)
+    localns.update({owner.__name__: owner for owner in owners})
+    unresolved: list[str] = []
+    for owner in owners:
+        for name, ann_str in own_annotations(owner).items():
+            if isinstance(ann_str, str):
+                try:
+                    eval(ann_str, globalns, localns)  # pylint: disable=eval-used
+                except (NameError, AttributeError) as err:
+                    unresolved.append(f"{name}: {ann_str} ({err})")

Review Comment:
   Good catch. I updated the diagnostic evaluation to catch `Exception`, so failures from arbitrary annotation expressions are included in the final unresolved-forward-reference `TypeError` while `BaseException` subclasses such as `KeyboardInterrupt` and `SystemExit` still propagate. I also added an end-to-end regression with a missing type followed by `len(1)`; before this change it leaked the inner `TypeError`, and now the final diagnostic includes both fields. The complete `test_dataclass_py_class.py` file passes (387 passed, 1 version-gated skip), and the scoped pre-commit checks pass. Thanks!



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3576163649


##########
python/tvm_ffi/dataclasses/_resolve_fields.py:
##########
@@ -0,0 +1,462 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Forward-annotation resolution for ``@py_class`` registration.
+
+``@py_class`` registers a Python type before it resolves field annotations, so
+self-referential and mutually recursive annotations can refer to classes that
+are already present in the FFI type registry.  This module owns that early
+registration step, the per-module local namespace used by
+``typing.get_type_hints``, and the queue of classes whose annotations must be
+retried after later definitions become available.
+
+When a class is ready to finalize, this module lazily imports
+``py_class.on_fields_resolved``.  Keeping the finalizer import local preserves
+the boundary between annotation resolution and field registration while avoiding
+a top-level import cycle.
+"""
+
+from __future__ import annotations
+
+import sys
+import typing
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .. import core
+from .field import KW_ONLY
+
+if TYPE_CHECKING:
+    from ..core import TypeInfo
+else:
+    TypeInfo = Any
+
+ResolvedFields = tuple[list[type], dict[type, dict[str, Any]]]
+
+
+# ---------------------------------------------------------------------------
+# Module-level state
+# ---------------------------------------------------------------------------
+#
+# ``@py_class`` registration happens in two phases:
+#
+#   Phase 1 (register_type_without_fields)
+#       Allocates a C-level type index and inserts the class into the
+#       global type registry.  This must happen early so that self-
+#       referential and mutually-referential annotations can resolve
+#       the class via ``TypeSchema.from_annotation()``.  Phase 1 always
+#       succeeds or raises immediately for invalid parents.  Decorator
+#       options are stored by py_class.py on ``TypeInfo._decorator_args``.
+#
+#   Phase 2 (py_class.on_fields_resolved)
+#       Resolves string annotations via ``typing.get_type_hints``,
+#       returns per-owner resolved hints, and asks py_class.py to
+#       materialize ``Field`` objects, register fields/methods/type
+#       attributes with the Cython layer, and install dataclass dunders.
+#
+#       If ``get_type_hints`` raises ``NameError`` (forward reference
+#       not yet defined), the class is added to ``_PENDING_CLASSES``
+#       and retried after each successful phase-2.  If phase-2 fails
+#       for any other reason, ``rollback_registration`` undoes phase-1
+#       so the type key can be reused.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _PendingClass:
+    """Resolution state for a class waiting on unresolved annotations.
+
+    Only data needed to retry annotation resolution is stored here.  Decorator
+    options live on ``type_info._decorator_args`` so deferred and immediate
+    finalization use the same source of truth.
+    """
+
+    cls: type
+    type_info: TypeInfo
+    globalns: dict[str, Any]
+
+
+#: Classes whose phase-2 (field registration) was deferred because
+#: ``typing.get_type_hints`` raised ``NameError`` on an unresolved
+#: forward reference.  Retried after each successful phase-2 via
+#: :func:`flush_pending`.
+_PENDING_CLASSES: list[_PendingClass] = []
+
+#: Per-module mapping of ``class.__name__ → class`` for every
+#: ``@py_class``-decorated type.  Used as *localns* when resolving
+#: annotations so that mutual references between classes in the same
+#: module work even before the second class is assigned to the module
+#: variable by Python.
+_PY_CLASS_BY_MODULE: dict[str, dict[str, type]] = {}
+
+
+class _KWOnlyAnnotation:
+    """Type-valued stand-in accepted by ``typing.get_type_hints``."""
+
+
+def _is_kw_only_annotation(annotation: Any) -> bool:
+    if annotation is KW_ONLY or annotation is _KWOnlyAnnotation:
+        return True
+    if isinstance(annotation, str):
+        return annotation == "KW_ONLY" or annotation.endswith(".KW_ONLY")
+    forward_arg = getattr(annotation, "__forward_arg__", None)
+    if isinstance(forward_arg, str):
+        return forward_arg == "KW_ONLY" or forward_arg.endswith(".KW_ONLY")
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Phase 1: type registration
+# ---------------------------------------------------------------------------
+
+
+def _registered_type_info(cls: type) -> TypeInfo | None:
+    """Return the TypeInfo registered directly for *cls*, not inherited metadata."""
+    info = core._type_cls_to_type_info(cls)
+    if info is not None:
+        return info
+    return cls.__dict__.get("__tvm_ffi_type_info__", None)
+
+
+def register_type_without_fields(cls: type, type_key: str | None) -> TypeInfo:
+    """Register ``cls`` in the FFI type registry before resolving fields.
+
+    The returned :class:`~tvm_ffi.core.TypeInfo` has a type index, type key, and
+    Python class binding, but no field metadata yet.  This early registration is
+    what lets ``TypeSchema.from_annotation`` resolve references to ``cls`` while
+    the decorator is still running.
+
+    The class is also inserted into the module-local annotation namespace used
+    by :func:`resolve_type_hints_by_owner`, allowing sibling ``@py_class``
+    declarations in the same module to reference each other before the second
+    class has been assigned to the module global by Python.
+    """
+    parent_info = next(
+        (info for base in cls.__mro__[1:] if (info := _registered_type_info(base)) is not None),
+        None,
+    )
+    if parent_info is None:
+        raise TypeError(
+            f"{cls.__name__} must inherit from a registered FFI Object type (e.g. tvm_ffi.Object)"
+        )
+    if type_key is None:
+        type_key = f"{cls.__module__}.{cls.__qualname__}"
+    info = core._register_py_class(parent_info, type_key, cls)
+    setattr(cls, "__tvm_ffi_type_info__", info)
+    # Register in resolution namespace so sibling classes can find us.
+    _PY_CLASS_BY_MODULE.setdefault(cls.__module__, {})[cls.__name__] = cls
+    return info
+
+
+def rollback_registration(cls: type, type_info: TypeInfo) -> None:
+    """Undo Python-side state from :func:`register_type_without_fields`.
+
+    The C-level type index is permanently consumed (cannot be reclaimed),
+    but the Python-level registry dicts are cleaned up so a retry with
+    the same type key does not hit "already registered".  The dataclass marker
+    is also removed because failed phase-2 finalization means the class is not a
+    usable FFI dataclass.
+    """
+    # Remove from the Cython-level registry dicts (TYPE_KEY_TO_INFO,
+    # TYPE_CLS_TO_INFO, TYPE_INDEX_TO_INFO, TYPE_INDEX_TO_CLS).
+    core._rollback_py_class(type_info)  # ty: ignore[unresolved-attribute]
+    # Remove from our own module-level resolution namespace.
+    _PY_CLASS_BY_MODULE.get(cls.__module__, {}).pop(cls.__name__, None)
+    for attr in ("__tvm_ffi_type_info__", "__ffi_is_dataclass__"):
+        try:
+            delattr(cls, attr)
+        except AttributeError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Annotation resolution
+# ---------------------------------------------------------------------------
+
+
+def own_annotations(cls: type) -> dict[str, Any]:
+    """Return annotations declared directly on ``cls`` without MRO merging."""
+    # Python 3.14+ (PEP 749): annotations are lazily evaluated via
+    # __annotate__ and no longer stored directly in __dict__.  getattr()
+    # triggers evaluation and returns per-class annotations correctly.
+    # On Python < 3.14, getattr() follows MRO and returns *parent*
+    # annotations when the child has none — use __dict__ to avoid that.
+    if sys.version_info >= (3, 14):
+        return getattr(cls, "__annotations__", {})
+    return cls.__dict__.get("__annotations__", {})
+
+
+def _field_owner_classes(cls: type) -> list[type]:
+    """Return local MRO entries whose annotations become fields on ``cls``.
+
+    A Python subclass of a registered FFI parent may include unregistered mixin
+    bases before the registered parent.  Those mixin annotations are owned by
+    the new Python type and should be registered together with ``cls``.  Fields
+    already represented by the nearest registered parent are excluded.
+    """
+    registered_parent = next(
+        (b for b in cls.__mro__[1:] if _registered_type_info(b) is not None), object
+    )
+    represented = set(registered_parent.__mro__)
+    return [
+        b
+        for b in reversed(cls.__mro__)
+        if b is not object and b not in represented and own_annotations(b)
+    ]
+
+
+def _build_localns(cls: type, *, cross_module: bool = False) -> dict[str, Any]:
+    """Build the localns dict for resolving ``cls``'s annotations.
+
+    By default, includes only classes from ``cls.__module__``, preserving
+    standard Python name resolution semantics.  When ``cross_module=True``,
+    also includes classes from all other registered modules as a fallback
+    — this is needed when ``cls`` has a forward reference to a class in
+    another module that can't appear in ``cls.__module__``'s globals due
+    to a circular import (e.g. the target is imported only under
+    ``if TYPE_CHECKING:``).
+
+    Cross-module entries are added with ``setdefault`` so same-module
+    classes and the class itself always take precedence over foreign
+    classes with the same ``__name__``.
+    """
+    localns = dict(_PY_CLASS_BY_MODULE.get(cls.__module__, {}))
+    localns[cls.__name__] = cls
+    if cross_module:
+        for mod_name, mod_classes in list(_PY_CLASS_BY_MODULE.items()):
+            if mod_name == cls.__module__:
+                continue
+            for name, klass in mod_classes.items():
+                localns.setdefault(name, klass)
+    return localns
+
+
+def _resolve_own_type_hints(
+    owner: type,
+    globalns: dict[str, Any],
+    localns: dict[str, Any],
+) -> dict[str, Any]:
+    """Resolve only annotations declared directly on ``owner``.
+
+    ``typing.get_type_hints(cls)`` merges annotations across the full MRO.
+    That is wrong for py_class phase 2 because inherited C++/c_class fields
+    are already registered by the parent type.  Resolving only the owner
+    annotations also avoids evaluating parent annotations in the child
+    module's namespace.
+
+    Python 3.10's ``typing.get_type_hints`` rejects ``dataclasses.KW_ONLY``
+    because it is a singleton, not a type.  Replace it in the temporary shim
+    annotations, then restore it in the resolved hints.
+    """
+    annotations = own_annotations(owner)
+    if not annotations:
+        return {}
+    shim_annotations = dict(annotations)
+    kw_only_names: list[str] = []
+    for name, annotation in annotations.items():
+        if _is_kw_only_annotation(annotation):
+            shim_annotations[name] = _KWOnlyAnnotation
+            kw_only_names.append(name)
+    shim = type(
+        f"_{owner.__name__}OwnAnnotations",
+        (),
+        {"__annotations__": shim_annotations, "__module__": owner.__module__},
+    )
+    kwargs: dict[str, Any] = {"globalns": globalns, "localns": localns}
+    if sys.version_info >= (3, 11):
+        kwargs["include_extras"] = True
+    hints = typing.get_type_hints(shim, **kwargs)
+    for name in kw_only_names:
+        hints[name] = KW_ONLY
+    return hints
+
+
+def resolve_type_hints_by_owner(
+    cls: type,
+    globalns: dict[str, Any],
+) -> ResolvedFields | None:
+    """Resolve field annotations grouped by owner class.
+
+    Returns ``(owners, hints_by_owner)`` when every annotation can be resolved.
+    Returns :data:`None` when a forward reference is still unavailable, signaling
+    that the caller should defer field registration and retry later.
+    """
+    # Resolve string annotations to types; return None (defer) on NameError.
+    #
+    # First try with module-scoped localns (standard Python name resolution).
+    # On NameError, retry with a cross-module localns that includes classes
+    # from every registered module — this handles circular imports where the
+    # target of a forward reference is imported only under TYPE_CHECKING and
+    # therefore never enters the declaring module's globals.
+    owners = _field_owner_classes(cls)
+    localns = _build_localns(cls)
+    localns.update({owner.__name__: owner for owner in owners})
+    try:
+        hints_by_owner = {
+            owner: _resolve_own_type_hints(
+                owner,
+                getattr(sys.modules.get(owner.__module__, None), "__dict__", globalns),
+                localns,
+            )
+            for owner in owners
+        }
+    except (NameError, AttributeError):
+        localns = _build_localns(cls, cross_module=True)
+        localns.update({owner.__name__: owner for owner in owners})
+        try:
+            hints_by_owner = {
+                owner: _resolve_own_type_hints(
+                    owner,
+                    getattr(sys.modules.get(owner.__module__, None), "__dict__", globalns),
+                    localns,
+                )
+                for owner in owners
+            }
+        except (NameError, AttributeError):
+            return None
+    return owners, hints_by_owner
+
+
+# ---------------------------------------------------------------------------
+# Deferred resolution
+# ---------------------------------------------------------------------------
+
+
+def flush_pending() -> None:
+    """Retry deferred classes until no additional annotations resolve.
+
+    A successful finalization can make another pending class resolvable, so this
+    function runs to a fixed point.  The field-registration finalizer is imported
+    lazily to keep this module focused on resolution and to avoid an import
+    cycle with :mod:`tvm_ffi.dataclasses.py_class`.
+    """
+    from .py_class import on_fields_resolved  # noqa: PLC0415
+
+    changed = True
+    while changed:
+        changed = False
+        remaining: list[_PendingClass] = []
+        for entry in _PENDING_CLASSES:
+            resolved = resolve_type_hints_by_owner(entry.cls, entry.globalns)
+            if resolved is None:
+                remaining.append(entry)
+            else:
+                on_fields_resolved(entry.type_info, resolved)
+                changed = True
+        _PENDING_CLASSES[:] = remaining
+
+
+def _raise_unresolved_forward_reference(cls: type, globalns: dict[str, Any]) -> None:
+    """Raise :class:`TypeError` listing the annotations that cannot be resolved."""
+    localns = _build_localns(cls, cross_module=True)
+    owners = _field_owner_classes(cls)
+    localns.update({owner.__name__: owner for owner in owners})
+    unresolved: list[str] = []
+    for owner in owners:
+        for name, ann_str in own_annotations(owner).items():
+            if isinstance(ann_str, str):
+                try:
+                    eval(ann_str, globalns, localns)  # pylint: disable=eval-used
+                except (NameError, AttributeError) as err:
+                    unresolved.append(f"{name}: {ann_str} ({err})")

Review Comment:
   This is a bit too defensive, but updated



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3576146273


##########
python/tvm_ffi/dataclasses/_resolve_fields.py:
##########
@@ -0,0 +1,462 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Forward-annotation resolution for ``@py_class`` registration.
+
+``@py_class`` registers a Python type before it resolves field annotations, so
+self-referential and mutually recursive annotations can refer to classes that
+are already present in the FFI type registry.  This module owns that early
+registration step, the per-module local namespace used by
+``typing.get_type_hints``, and the queue of classes whose annotations must be
+retried after later definitions become available.
+
+When a class is ready to finalize, this module lazily imports
+``py_class.on_fields_resolved``.  Keeping the finalizer import local preserves
+the boundary between annotation resolution and field registration while avoiding
+a top-level import cycle.
+"""
+
+from __future__ import annotations
+
+import sys
+import typing
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .. import core
+from .field import KW_ONLY
+
+if TYPE_CHECKING:
+    from ..core import TypeInfo
+else:
+    TypeInfo = Any
+
+ResolvedFields = tuple[list[type], dict[type, dict[str, Any]]]
+
+
+# ---------------------------------------------------------------------------
+# Module-level state
+# ---------------------------------------------------------------------------
+#
+# ``@py_class`` registration happens in two phases:
+#
+#   Phase 1 (register_type_without_fields)
+#       Allocates a C-level type index and inserts the class into the
+#       global type registry.  This must happen early so that self-
+#       referential and mutually-referential annotations can resolve
+#       the class via ``TypeSchema.from_annotation()``.  Phase 1 always
+#       succeeds or raises immediately for invalid parents.  Decorator
+#       options are stored by py_class.py on ``TypeInfo._decorator_args``.
+#
+#   Phase 2 (py_class.on_fields_resolved)
+#       Resolves string annotations via ``typing.get_type_hints``,
+#       returns per-owner resolved hints, and asks py_class.py to
+#       materialize ``Field`` objects, register fields/methods/type
+#       attributes with the Cython layer, and install dataclass dunders.
+#
+#       If ``get_type_hints`` raises ``NameError`` (forward reference
+#       not yet defined), the class is added to ``_PENDING_CLASSES``
+#       and retried after each successful phase-2.  If phase-2 fails
+#       for any other reason, ``rollback_registration`` undoes phase-1
+#       so the type key can be reused.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _PendingClass:
+    """Resolution state for a class waiting on unresolved annotations.
+
+    Only data needed to retry annotation resolution is stored here.  Decorator
+    options live on ``type_info._decorator_args`` so deferred and immediate
+    finalization use the same source of truth.
+    """
+
+    cls: type
+    type_info: TypeInfo
+    globalns: dict[str, Any]
+
+
+#: Classes whose phase-2 (field registration) was deferred because
+#: ``typing.get_type_hints`` raised ``NameError`` on an unresolved
+#: forward reference.  Retried after each successful phase-2 via
+#: :func:`flush_pending`.
+_PENDING_CLASSES: list[_PendingClass] = []
+
+#: Per-module mapping of ``class.__name__ → class`` for every
+#: ``@py_class``-decorated type.  Used as *localns* when resolving
+#: annotations so that mutual references between classes in the same
+#: module work even before the second class is assigned to the module
+#: variable by Python.
+_PY_CLASS_BY_MODULE: dict[str, dict[str, type]] = {}
+
+
+class _KWOnlyAnnotation:
+    """Type-valued stand-in accepted by ``typing.get_type_hints``."""
+
+
+def _is_kw_only_annotation(annotation: Any) -> bool:
+    if annotation is KW_ONLY or annotation is _KWOnlyAnnotation:
+        return True
+    if isinstance(annotation, str):
+        return annotation == "KW_ONLY" or annotation.endswith(".KW_ONLY")
+    forward_arg = getattr(annotation, "__forward_arg__", None)
+    if isinstance(forward_arg, str):
+        return forward_arg == "KW_ONLY" or forward_arg.endswith(".KW_ONLY")
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Phase 1: type registration
+# ---------------------------------------------------------------------------
+
+
+def _registered_type_info(cls: type) -> TypeInfo | None:
+    """Return the TypeInfo registered directly for *cls*, not inherited metadata."""
+    info = core._type_cls_to_type_info(cls)
+    if info is not None:
+        return info
+    return cls.__dict__.get("__tvm_ffi_type_info__", None)
+
+
+def register_type_without_fields(cls: type, type_key: str | None) -> TypeInfo:
+    """Register ``cls`` in the FFI type registry before resolving fields.
+
+    The returned :class:`~tvm_ffi.core.TypeInfo` has a type index, type key, and
+    Python class binding, but no field metadata yet.  This early registration is
+    what lets ``TypeSchema.from_annotation`` resolve references to ``cls`` while
+    the decorator is still running.
+
+    The class is also inserted into the module-local annotation namespace used
+    by :func:`resolve_type_hints_by_owner`, allowing sibling ``@py_class``
+    declarations in the same module to reference each other before the second
+    class has been assigned to the module global by Python.
+    """
+    parent_info = next(
+        (info for base in cls.__mro__[1:] if (info := _registered_type_info(base)) is not None),
+        None,
+    )
+    if parent_info is None:
+        raise TypeError(
+            f"{cls.__name__} must inherit from a registered FFI Object type (e.g. tvm_ffi.Object)"
+        )
+    if type_key is None:
+        type_key = f"{cls.__module__}.{cls.__qualname__}"
+    info = core._register_py_class(parent_info, type_key, cls)
+    setattr(cls, "__tvm_ffi_type_info__", info)
+    # Register in resolution namespace so sibling classes can find us.
+    _PY_CLASS_BY_MODULE.setdefault(cls.__module__, {})[cls.__name__] = cls
+    return info
+
+
+def rollback_registration(cls: type, type_info: TypeInfo) -> None:
+    """Undo Python-side state from :func:`register_type_without_fields`.
+
+    The C-level type index is permanently consumed (cannot be reclaimed),
+    but the Python-level registry dicts are cleaned up so a retry with
+    the same type key does not hit "already registered".  The dataclass marker
+    is also removed because failed phase-2 finalization means the class is not a
+    usable FFI dataclass.
+    """
+    # Remove from the Cython-level registry dicts (TYPE_KEY_TO_INFO,
+    # TYPE_CLS_TO_INFO, TYPE_INDEX_TO_INFO, TYPE_INDEX_TO_CLS).
+    core._rollback_py_class(type_info)  # ty: ignore[unresolved-attribute]
+    # Remove from our own module-level resolution namespace.
+    _PY_CLASS_BY_MODULE.get(cls.__module__, {}).pop(cls.__name__, None)
+    for attr in ("__tvm_ffi_type_info__", "__ffi_is_dataclass__"):
+        try:
+            delattr(cls, attr)
+        except AttributeError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Annotation resolution
+# ---------------------------------------------------------------------------
+
+
+def own_annotations(cls: type) -> dict[str, Any]:
+    """Return annotations declared directly on ``cls`` without MRO merging."""
+    # Python 3.14+ (PEP 749): annotations are lazily evaluated via
+    # __annotate__ and no longer stored directly in __dict__.  getattr()
+    # triggers evaluation and returns per-class annotations correctly.
+    # On Python < 3.14, getattr() follows MRO and returns *parent*
+    # annotations when the child has none — use __dict__ to avoid that.
+    if sys.version_info >= (3, 14):
+        return getattr(cls, "__annotations__", {})
+    return cls.__dict__.get("__annotations__", {})
+
+
+def _field_owner_classes(cls: type) -> list[type]:
+    """Return local MRO entries whose annotations become fields on ``cls``.
+
+    A Python subclass of a registered FFI parent may include unregistered mixin
+    bases before the registered parent.  Those mixin annotations are owned by
+    the new Python type and should be registered together with ``cls``.  Fields
+    already represented by the nearest registered parent are excluded.
+    """
+    registered_parent = next(
+        (b for b in cls.__mro__[1:] if _registered_type_info(b) is not None), object
+    )
+    represented = set(registered_parent.__mro__)
+    return [
+        b
+        for b in reversed(cls.__mro__)
+        if b is not object and b not in represented and own_annotations(b)
+    ]
+
+
+def _build_localns(cls: type, *, cross_module: bool = False) -> dict[str, Any]:
+    """Build the localns dict for resolving ``cls``'s annotations.
+
+    By default, includes only classes from ``cls.__module__``, preserving
+    standard Python name resolution semantics.  When ``cross_module=True``,
+    also includes classes from all other registered modules as a fallback
+    — this is needed when ``cls`` has a forward reference to a class in
+    another module that can't appear in ``cls.__module__``'s globals due
+    to a circular import (e.g. the target is imported only under
+    ``if TYPE_CHECKING:``).
+
+    Cross-module entries are added with ``setdefault`` so same-module
+    classes and the class itself always take precedence over foreign
+    classes with the same ``__name__``.
+    """
+    localns = dict(_PY_CLASS_BY_MODULE.get(cls.__module__, {}))
+    localns[cls.__name__] = cls
+    if cross_module:
+        for mod_name, mod_classes in list(_PY_CLASS_BY_MODULE.items()):
+            if mod_name == cls.__module__:
+                continue
+            for name, klass in mod_classes.items():
+                localns.setdefault(name, klass)
+    return localns
+
+
+def _resolve_own_type_hints(
+    owner: type,
+    globalns: dict[str, Any],
+    localns: dict[str, Any],
+) -> dict[str, Any]:
+    """Resolve only annotations declared directly on ``owner``.
+
+    ``typing.get_type_hints(cls)`` merges annotations across the full MRO.
+    That is wrong for py_class phase 2 because inherited C++/c_class fields
+    are already registered by the parent type.  Resolving only the owner
+    annotations also avoids evaluating parent annotations in the child
+    module's namespace.
+
+    Python 3.10's ``typing.get_type_hints`` rejects ``dataclasses.KW_ONLY``
+    because it is a singleton, not a type.  Replace it in the temporary shim
+    annotations, then restore it in the resolved hints.
+    """
+    annotations = own_annotations(owner)
+    if not annotations:
+        return {}
+    shim_annotations = dict(annotations)
+    kw_only_names: list[str] = []
+    for name, annotation in annotations.items():
+        if _is_kw_only_annotation(annotation):
+            shim_annotations[name] = _KWOnlyAnnotation
+            kw_only_names.append(name)
+    shim = type(
+        f"_{owner.__name__}OwnAnnotations",
+        (),
+        {"__annotations__": shim_annotations, "__module__": owner.__module__},
+    )
+    kwargs: dict[str, Any] = {"globalns": globalns, "localns": localns}
+    if sys.version_info >= (3, 11):
+        kwargs["include_extras"] = True
+    hints = typing.get_type_hints(shim, **kwargs)
+    for name in kw_only_names:
+        hints[name] = KW_ONLY
+    return hints
+
+
+def resolve_type_hints_by_owner(
+    cls: type,
+    globalns: dict[str, Any],
+) -> ResolvedFields | None:
+    """Resolve field annotations grouped by owner class.
+
+    Returns ``(owners, hints_by_owner)`` when every annotation can be resolved.
+    Returns :data:`None` when a forward reference is still unavailable, signaling
+    that the caller should defer field registration and retry later.
+    """
+    # Resolve string annotations to types; return None (defer) on NameError.
+    #
+    # First try with module-scoped localns (standard Python name resolution).
+    # On NameError, retry with a cross-module localns that includes classes
+    # from every registered module — this handles circular imports where the
+    # target of a forward reference is imported only under TYPE_CHECKING and
+    # therefore never enters the declaring module's globals.
+    owners = _field_owner_classes(cls)
+    localns = _build_localns(cls)
+    localns.update({owner.__name__: owner for owner in owners})
+    try:
+        hints_by_owner = {
+            owner: _resolve_own_type_hints(
+                owner,
+                getattr(sys.modules.get(owner.__module__, None), "__dict__", globalns),
+                localns,
+            )
+            for owner in owners
+        }
+    except (NameError, AttributeError):
+        localns = _build_localns(cls, cross_module=True)
+        localns.update({owner.__name__: owner for owner in owners})
+        try:
+            hints_by_owner = {
+                owner: _resolve_own_type_hints(
+                    owner,
+                    getattr(sys.modules.get(owner.__module__, None), "__dict__", globalns),
+                    localns,
+                )
+                for owner in owners
+            }
+        except (NameError, AttributeError):
+            return None
+    return owners, hints_by_owner
+
+
+# ---------------------------------------------------------------------------
+# Deferred resolution
+# ---------------------------------------------------------------------------
+
+
+def flush_pending() -> None:
+    """Retry deferred classes until no additional annotations resolve.
+
+    A successful finalization can make another pending class resolvable, so this
+    function runs to a fixed point.  The field-registration finalizer is imported
+    lazily to keep this module focused on resolution and to avoid an import
+    cycle with :mod:`tvm_ffi.dataclasses.py_class`.
+    """
+    from .py_class import on_fields_resolved  # noqa: PLC0415
+
+    changed = True
+    while changed:
+        changed = False
+        remaining: list[_PendingClass] = []
+        for entry in _PENDING_CLASSES:
+            resolved = resolve_type_hints_by_owner(entry.cls, entry.globalns)
+            if resolved is None:
+                remaining.append(entry)
+            else:
+                on_fields_resolved(entry.type_info, resolved)
+                changed = True
+        _PENDING_CLASSES[:] = remaining

Review Comment:
   it's too defensive



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] refactor(dataclasses)!: separate field resolution and native lifetimes [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #663:
URL: https://github.com/apache/tvm-ffi/pull/663#discussion_r3576145002


##########
include/tvm/ffi/device.h:
##########
@@ -0,0 +1,155 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/*!
+ * \file tvm/ffi/device.h
+ * \brief Device handling.
+ */
+#ifndef TVM_FFI_DEVICE_H_
+#define TVM_FFI_DEVICE_H_
+
+#include <dlpack/dlpack.h>
+#include <tvm/ffi/string.h>
+#include <tvm/ffi/type_traits.h>
+
+#include <cstdint>
+#include <limits>
+#include <optional>
+#include <string>
+#include <string_view>
+
+namespace tvm {
+namespace ffi {
+namespace details {
+
+TVM_FFI_INLINE static std::optional<DLDeviceType> TryParseDLDeviceType(std::string_view name) {
+  if (name == "llvm" || name == "cpu" || name == "c" || name == "test") return kDLCPU;
+  if (name == "cuda" || name == "nvptx") return kDLCUDA;
+  if (name == "cl" || name == "opencl") return kDLOpenCL;
+  if (name == "vulkan") return kDLVulkan;
+  if (name == "metal") return kDLMetal;
+  if (name == "vpi") return kDLVPI;
+  if (name == "rocm") return kDLROCM;
+  if (name == "ext_dev") return kDLExtDev;
+  if (name == "hexagon") return kDLHexagon;
+  if (name == "webgpu") return kDLWebGPU;
+  if (name == "maia") return kDLMAIA;
+  if (name == "trn") return kDLTrn;
+  return std::nullopt;
+}
+
+TVM_FFI_INLINE static std::optional<int32_t> TryParseDLDeviceIndex(std::string_view index) {
+  if (index.empty()) return std::nullopt;
+  int64_t sign = 1;
+  size_t pos = 0;
+  if (index[0] == '-') {
+    sign = -1;
+    pos = 1;
+  }
+  if (pos >= index.size()) return std::nullopt;
+  int64_t value = 0;
+  for (; pos < index.size(); ++pos) {
+    char ch = index[pos];
+    if (ch < '0' || ch > '9') return std::nullopt;
+    value = value * 10 + (ch - '0');
+    if (value > std::numeric_limits<int32_t>::max()) return std::nullopt;
+  }
+  value *= sign;
+  if (value < std::numeric_limits<int32_t>::min() || value > std::numeric_limits<int32_t>::max()) {
+    return std::nullopt;
+  }
+  return static_cast<int32_t>(value);
+}

Review Comment:
   it's too defensive



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org