Fix Python overload naming and interface-parameter dispatch

.github/workflows/build.yml

@@ -543,12 +543,15 @@ jobs:
           .\eng\release\python\test_generated_python_long_paths.ps1 `
             -Python .\bindings\py\.venv\Scripts\python.exe `
             -Codegen $env:DYNWINRT_CODEGEN
-      - name: Test generated implementation symbol identities
+      - name: Test generated implementation and overload identities
         shell: pwsh
         run: |
           $env:DYNWINRT_TEST_PYTHON = (Resolve-Path .\bindings\py\.venv\Scripts\python.exe).Path
           $env:DYNWINRT_REQUIRE_IMPLEMENTATION_RUNTIME = '1'
-          cargo test -p dynwinrt-codegen --test implementation_naming_test --test python_released_implementation_test
+          cargo test -p dynwinrt-codegen `
+            --test implementation_naming_test `
+            --test python_overload_legacy_compat_test `
+            --test python_released_implementation_test
       - name: Run E2E tests
         run: .\tests\e2e\e2e_test.ps1 -SkipBuild -Codegen $env:DYNWINRT_CODEGEN
       # This optional-SDK behavioral smoke is separate from generated coverage

bindings/py/README.md

@@ -15,6 +15,9 @@ dynwinrt-codegen generate --namespace Windows.Foundation --class-name Uri `
 Generated package manifests pin `dynwinrt` to the exact version of
 `dynwinrt-codegen` that produced them. The runtime wheel includes
 `__init__.pyi` and `py.typed` for static type checking.
+Do not mix generated bindings with an older runtime wheel. Upgrade to the
+matching runtime version and regenerate all Python bindings together; generated
+interface overloads fail explicitly when a required native guard is missing.
 
 Generated `IReference<T>` values are projected as `T | None`; native values,
 `None`, and generated `IReference_*` wrappers are accepted as inputs.
@@ -170,8 +173,26 @@ def work(action: DynWinRTValue) -> None:
 operation = ThreadPool.run_async(work)
 ```
 
-WinRT flags enums are projected as `enum.IntFlag`. Overloaded methods share one
+`ThreadPool.run_async(handler)` intentionally retains its original single
+argument and exact callback annotation, so mypy can infer the type of an
+unannotated callback lambda. Its priority and options overloads remain
+separate as `run_with_priority_async(handler, priority)` and
+`run_with_priority_and_options_async(handler, priority, options)`. These are
+distinct names in both generated Python and `.pyi`; passing priority or options
+to `run_async` is not supported.
+
+WinRT flags enums are projected as `enum.IntFlag`. Most overloaded methods share one
 Python name with runtime type/arity dispatch and `typing.overload` declarations.
+That name is the documented (CLR) method name, so `StorageFile.CopyAsync`
+overloads are all `copy_async(...)`. The unique `[Overload]` ABI names emitted by
+earlier releases, such as `copy_overload` or `launch_file_with_options_async`,
+remain available as compatibility aliases that keep calling the same overload.
+A method keeps its earlier name when the documented name would clash with
+another member, such as a property or the generated `close()`. Interface
+parameters of overloads accept any object that implements the interface, such
+as a runtime class instance or a `DynWinRTValue`, including a raw async
+operation that implements `IAsyncInfo`. Native QueryInterface failures other
+than `E_NOINTERFACE` propagate instead of silently choosing another overload.
 Activatable runtime classes use normal constructors, for example
 `Uri("https://example.com")`. Constructor overloads come only from WinMD
 `ActivatableAttribute` and public `ComposableAttribute` declarations. Classes

bindings/py/dynwinrt.pyi

@@ -466,6 +466,7 @@ class DynWinRTValue:
     def to_guid(self) -> WinGUID: ...
     def to_bytes(self) -> bytes: ...
     def is_null(self) -> bool: ...
+    def _try_query_interface(self, iid: WinGUID) -> bool: ...
     # True after release(), release_projected(), or a closing
     # projected_lifetime_scope(); a WinRT null reference is not released.
     def is_released(self) -> bool: ...

bindings/py/src/runtime.rs

@@ -1721,6 +1721,29 @@ impl DynWinRTValue {
         self.0.is_null_object()
     }
 
+    /// Guard-only QueryInterface probe; never treats a native failure as a non-match.
+    fn _try_query_interface(&self, iid: &WinGUID) -> PyResult<bool> {
+        self.ensure_live()?;
+        if !matches!(
+            &self.0,
+            dynwinrt::WinRTValue::Object(_) | dynwinrt::WinRTValue::Async(_)
+        ) {
+            return Ok(false);
+        }
+        match self.0.cast(&iid.0) {
+            Ok(interface) => {
+                drop(interface);
+                Ok(true)
+            }
+            Err(dynwinrt::Error::WindowsError(error))
+                if error.code() == windows::Win32::Foundation::E_NOINTERFACE =>
+            {
+                Ok(false)
+            }
+            Err(error) => Err(map_dynwinrt_error(error)),
+        }
+    }
+
     /// Whether `release()` has run on this value, directly or through
     /// `release_projected()` or a closing `projected_lifetime_scope()`.
     ///
@@ -2675,6 +2698,84 @@ pub fn get_computer_name() -> PyResult<String> {
 mod tests {
     use super::*;
     use pyo3::types::PyDict;
+    use std::ffi::c_void;
+    use std::sync::atomic::{AtomicU32, Ordering};
+
+    #[derive(Default)]
+    struct QueryCounts {
+        queries: AtomicU32,
+        addrefs: AtomicU32,
+        releases: AtomicU32,
+    }
+
+    #[repr(C)]
+    struct QueryProbe {
+        vtable: *const windows::core::IUnknown_Vtbl,
+        references: AtomicU32,
+        counts: Arc<QueryCounts>,
+    }
+
+    impl QueryProbe {
+        const SUPPORTED: GUID = IUnknown::IID;
+        const FAILURE: GUID = GUID::from_u128(0x12113896_999b_42d5_87c1_7c68e83592eb);
+        const UNKNOWN: GUID = GUID::from_u128(0x6192657c_dbc2_4262_98c8_8ead575ac434);
+        const VTABLE: windows::core::IUnknown_Vtbl = windows::core::IUnknown_Vtbl {
+            QueryInterface: Self::query,
+            AddRef: Self::add_ref,
+            Release: Self::release,
+        };
+
+        fn new() -> (IUnknown, Arc<QueryCounts>) {
+            let counts = Arc::new(QueryCounts::default());
+            let object = Box::new(Self {
+                vtable: &Self::VTABLE,
+                references: AtomicU32::new(1),
+                counts: counts.clone(),
+            });
+            (
+                unsafe { IUnknown::from_raw(Box::into_raw(object).cast()) },
+                counts,
+            )
+        }
+
+        unsafe extern "system" fn query(
+            this: *mut c_void,
+            iid: *const GUID,
+            result: *mut *mut c_void,
+        ) -> windows::core::HRESULT {
+            if iid.is_null() || result.is_null() {
+                return windows::core::HRESULT(0x80004003u32 as i32);
+            }
+            let object = unsafe { &*this.cast::<Self>() };
+            object.counts.queries.fetch_add(1, Ordering::SeqCst);
+            unsafe { *result = std::ptr::null_mut() };
+            match unsafe { *iid } {
+                Self::SUPPORTED => {
+                    unsafe { *result = this };
+                    unsafe { Self::add_ref(this) };
+                    windows::core::HRESULT(0)
+                }
+                Self::FAILURE => windows::core::HRESULT(0x80004005u32 as i32),
+                _ => windows::Win32::Foundation::E_NOINTERFACE,
+            }
+        }
+
+        unsafe extern "system" fn add_ref(this: *mut c_void) -> u32 {
+            let object = unsafe { &*this.cast::<Self>() };
+            object.counts.addrefs.fetch_add(1, Ordering::SeqCst);
+            object.references.fetch_add(1, Ordering::SeqCst) + 1
+        }
+
+        unsafe extern "system" fn release(this: *mut c_void) -> u32 {
+            let object = unsafe { &*this.cast::<Self>() };
+            object.counts.releases.fetch_add(1, Ordering::SeqCst);
+            let remaining = object.references.fetch_sub(1, Ordering::SeqCst) - 1;
+            if remaining == 0 {
+                unsafe { drop(Box::from_raw(this.cast::<Self>())) };
+            }
+            remaining
+        }
+    }
 
     #[repr(C)]
     struct TestDelegateVtbl {
@@ -2706,6 +2807,65 @@ mod tests {
         assert_eq!(array.to_i32_list().unwrap(), vec![0, 0x80004005u32 as i32]);
     }
 
+    #[test]
+    fn private_query_guard_releases_successful_qi_and_preserves_other_failures() {
+        Python::initialize();
+        Python::attach(|py| {
+            let (object, counts) = QueryProbe::new();
+            let mut value = DynWinRTValue::new(dynwinrt::WinRTValue::Object(object));
+            assert!(
+                value
+                    ._try_query_interface(&WinGUID(QueryProbe::SUPPORTED))
+                    .unwrap()
+            );
+            assert_eq!(counts.addrefs.load(Ordering::SeqCst), 1);
+            assert_eq!(counts.releases.load(Ordering::SeqCst), 1);
+            assert!(
+                !value
+                    ._try_query_interface(&WinGUID(QueryProbe::UNKNOWN))
+                    .unwrap()
+            );
+            let error = value
+                ._try_query_interface(&WinGUID(QueryProbe::FAILURE))
+                .unwrap_err();
+            assert!(error.is_instance_of::<pyo3::exceptions::PyOSError>(py));
+            assert_eq!(
+                error
+                    .value(py)
+                    .getattr("winerror")
+                    .unwrap()
+                    .extract::<i32>()
+                    .unwrap(),
+                0x80004005u32 as i32
+            );
+            assert_eq!(counts.queries.load(Ordering::SeqCst), 3);
+            assert_eq!(counts.addrefs.load(Ordering::SeqCst), 1);
+            assert_eq!(counts.releases.load(Ordering::SeqCst), 1);
+
+            for payload in [
+                dynwinrt::WinRTValue::I32(5),
+                dynwinrt::WinRTValue::HString("scalar".into()),
+                dynwinrt::WinRTValue::Null,
+                dynwinrt::WinRTValue::RawPtr(std::ptr::null_mut()),
+            ] {
+                assert!(
+                    !DynWinRTValue::new(payload)
+                        ._try_query_interface(&WinGUID(QueryProbe::SUPPORTED))
+                        .unwrap()
+                );
+            }
+            assert_eq!(counts.queries.load(Ordering::SeqCst), 3);
+
+            value.release();
+            assert_eq!(counts.releases.load(Ordering::SeqCst), 2);
+            let released = value
+                ._try_query_interface(&WinGUID(QueryProbe::SUPPORTED))
+                .unwrap_err();
+            assert!(released.is_instance_of::<PyRuntimeError>(py));
+            assert!(released.to_string().contains("released"));
+        });
+    }
+
     #[test]
     fn detached_invocation_releases_the_gil_on_the_same_native_thread() {
         use dynwinrt::{

eng/ci/test_ci.py

@@ -241,7 +241,10 @@ def test_current_run_artifacts_and_no_consumer_rebuilds(self):
                               "npm run test:borrowed-copy"):
                 self.assertNotIn(forbidden, commands)
         runtime = "\n".join(step.get("run", "") for step in JOBS["e2e-runtime"]["steps"])
-        self.assertIn("cargo test -p dynwinrt-codegen --test implementation_naming_test", runtime)
+        self.assertIn("cargo test -p dynwinrt-codegen `", runtime)
+        self.assertIn("--test implementation_naming_test", runtime)
+        self.assertIn("--test python_overload_legacy_compat_test", runtime)
+        self.assertIn("--test python_released_implementation_test", runtime)
 
     def test_release_notes_validated_in_lightweight_lane(self):
         steps = [

tests/e2e/e2e_specs.json

@@ -154,7 +154,8 @@
         "args": ["en-US"]
       },
       "checks": [
-        { "kind": "property_equals", "member": "language_tag", "expected": "en-US" }
+        { "kind": "property_equals", "member": "language_tag", "expected": "en-US" },
+        { "kind": "language_comprehensive", "member": "self", "langs": ["py"] }
       ]
     },
     {
@@ -337,7 +338,8 @@
       "checks": [
         { "kind": "sequence_protocol", "member": "languages", "expected_size": 1 },
         { "kind": "datetime_roundtrip", "member": "date_time", "langs": ["py"] },
-        { "kind": "calendar_comprehensive", "member": "self" }
+        { "kind": "calendar_comprehensive", "member": "self" },
+        { "kind": "calendar_documented_overloads", "member": "month_as_string", "langs": ["py"] }
       ]
     },
     {
@@ -396,6 +398,16 @@
         { "kind": "work_item_callback_passthrough", "member": "run_async" }
       ]
     },
+    {
+      "id": "preallocated_work_item_delegate_constructor",
+      "namespace": "Windows.System.Threading.Core",
+      "class": "PreallocatedWorkItem",
+      "langs": ["py"],
+      "instantiate": { "kind": "none" },
+      "checks": [
+        { "kind": "preallocated_work_item_callback", "member": "run_async" }
+      ]
+    },
     {
       "id": "thread_pool_timer_callback_projection",
       "namespace": "Windows.System.Threading",
@@ -505,7 +517,9 @@
       "instantiate": { "kind": "none" },
       "checks": [
         { "kind": "async_memory_roundtrip", "member": "roundtrip", "write_value": 42 },
-        { "kind": "data_stream_scalar_roundtrip", "member": "roundtrip", "langs": ["py"] }
+        { "kind": "data_stream_scalar_roundtrip", "member": "roundtrip", "langs": ["py"] },
+        { "kind": "data_stream_constructor_roundtrip", "member": "__init__", "langs": ["py"] },
+        { "kind": "can_cast_non_object", "member": "_dynwinrt_can_cast", "langs": ["py"] }
       ]
     },
     {
@@ -528,6 +542,37 @@
         { "kind": "storage_query_temp_folder", "member": "query" }
       ]
     },
+    {
+      "id": "python_storage_file_copy_overloads",
+      "namespace": "Windows.Storage",
+      "class": "StorageFile",
+      "langs": ["py"],
+      "instantiate": { "kind": "none" },
+      "checks": [
+        { "kind": "storage_file_copy_overloads", "member": "copy_async" }
+      ]
+    },
+    {
+      "id": "python_stream_copy_overloads",
+      "namespace": "Windows.Storage.Streams",
+      "class": "RandomAccessStream",
+      "langs": ["py"],
+      "extra_classes": ["InMemoryRandomAccessStream", "DataWriter", "DataReader"],
+      "instantiate": { "kind": "none" },
+      "checks": [
+        { "kind": "random_access_stream_copy_overloads", "member": "copy_async" }
+      ]
+    },
+    {
+      "id": "python_decimal_formatter_overloads",
+      "namespace": "Windows.Globalization.NumberFormatting",
+      "class": "DecimalFormatter",
+      "langs": ["py"],
+      "instantiate": { "kind": "none" },
+      "checks": [
+        { "kind": "decimal_formatter_overloads", "member": "format" }
+      ]
+    },
     {
       "id": "issue_69_device_information_async_collection",
       "namespace": "Windows.Devices.Enumeration",
@@ -646,7 +691,8 @@
           "args": ["<root><child /></root>"],
           "property_path": ["document_element", "tag_name"],
           "expected": "root"
-        }
+        },
+        { "kind": "xml_document_load_overloads", "member": "load_xml", "langs": ["py"] }
       ]
     },
     {

tests/e2e/e2e_specs.schema.json

@@ -57,6 +57,7 @@
         "kind": {
           "enum": [
             "property_equals",
+            "language_comprehensive",
             "property_exists",
             "property_in_range",
             "method_equals",
@@ -99,11 +100,19 @@
              "constructor_overload_dispatch",
              "value_set_mapping",
              "data_stream_scalar_roundtrip",
+             "data_stream_constructor_roundtrip",
+             "can_cast_non_object",
              "calendar_comprehensive",
              "storage_query_temp_folder",
+             "storage_file_copy_overloads",
+             "random_access_stream_copy_overloads",
+             "decimal_formatter_overloads",
+             "xml_document_load_overloads",
+             "calendar_documented_overloads",
              "value_set_event_lifecycle",
              "map_changed_event_projection",
              "work_item_callback_passthrough",
+             "preallocated_work_item_callback",
              "timer_callback_projection",
              "static_event_native_delegate_passthrough",
              "nested_struct_runtime",