TOML based renaming in the bindings. (#2715)

All builtin bindings support renaming almost all of the interface (types, args, items, variants, etc)
via TOML definitions.

Fixes #2427, fixes #1426, fixes #2502

Author: mhammond

CHANGELOG.md

@@ -6,27 +6,28 @@
 
 ## [[UnreleasedUniFFIVersion]] (backend crates: [[UnreleasedBackendVersion]]) - (_[[ReleaseDate]]_)
 
-### ⚠️ Breaking Changes for external bindings authors ⚠️
-- The `module_path` field now stores full module paths rather than crate names only.
-  External bindings authors will probably need to make some minor changes to work with this.
-  See https://github.com/mozilla/uniffi-rs/pull/2695/ for examples.
-
-[All changes in [[UnreleasedUniFFIVersion]]](https://github.com/mozilla/uniffi-rs/compare/v0.30.0...HEAD).
-
 ### What's New?
 
-- Some support for methods and constructors on dataclasses for Python. ([#2706](https://
-  github.com/mozilla/uniffi-rs/pull/2706)).
-- Kotlin: Rust enums with nested payload types are generated using the inner type’s fully qualified
-  name, avoiding naming conflicts and allowing payloads to reuse the variant name ([#2698](https://
-  github.com/mozilla/uniffi-rs/pull/2698)).
+- All builtin bindings support renaming almost all of the interface (types, args, items, variants, etc) via TOML definitions -
+  [see the docs](https://mozilla.github.io/uniffi-rs/next/renaming.html).
+  ([#2715](https://github.com/mozilla/uniffi-rs/pull/2715))
+- Support for methods on dataclasses for Python. ([#2706](https://github.com/mozilla/uniffi-rs/pull/2706)).
 
 ### What's Fixed
 
+- Kotlin: Rust enums with nested payload types are generated using the inner type’s fully qualified
+  name, avoiding naming conflicts and allowing payloads to reuse the variant name ([#2698](https://github.com/mozilla/uniffi-rs/pull/2698)).
 - Kotlin: Enums and errors now support exporting trait methods (Display, Debug, Eq, Hash, Ord) via `toString()`,
   `equals()`, `hashCode()`, and `compareTo()` implementations. Flat enums only support exporting `Display`. ([#2700](https://github.com/mozilla/uniffi-rs/pull/2700)).
 - Kotlin: Initialization functions now have a stable ordering ([#2718](https://github.com/mozilla/uniffi-rs/pull/2718))
 
+### ⚠️ Breaking Changes for external bindings authors ⚠️
+- The `module_path` field now stores full module paths rather than crate names only.
+  External bindings authors will probably need to make some minor changes to work with this.
+  See https://github.com/mozilla/uniffi-rs/pull/2695/ for examples.
+
+[All changes in [[UnreleasedUniFFIVersion]]](https://github.com/mozilla/uniffi-rs/compare/v0.30.0...HEAD).
+
 ## v0.30.0 (backend crates: v0.30.0) - (_2025-10-08_)
 
 ### ⚠️ Breaking Changes ⚠️

docs/manual/src/kotlin/configuration.md

@@ -11,6 +11,7 @@ The generated Kotlin modules can be configured using a `uniffi.toml` configurati
 | `generate_immutable_records` | `false`                  | Whether to generate records with immutable fields (`val` instead of `var`). |
 | `custom_types`               |                          | A map which controls how custom types are exposed to Kotlin. See the [custom types section of the manual](../types/custom_types.md#custom-types-in-the-bindings-code)|
 | `external_packages`          |                          | A map of packages to be used for the specified external crates. The key is the Rust crate name, the value is the Kotlin package which will be used referring to types in that crate. See the [external types section of the manual](../types/remote_ext_types.md#kotlin)
+| `rename`                     |                          | A map to rename types, functions, methods, and their members in the generated Kotlin bindings. See the [renaming section](../renaming.md).
 | `android`                    | `false`                  | Used to toggle on Android specific optimizations
 | `android_cleaner`            | `android`                | Use the [`android.system.SystemCleaner`](https://developer.android.com/reference/android/system/SystemCleaner) instead of [`java.lang.ref.Cleaner`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ref/Cleaner.html). Fallback in both instances is the one shipped with JNA.
 | `kotlin_target_version`      | `"x.y.z"`                | When provided, it will enable features in the bindings supported for this version. The build process will fail if an invalid format is used.

docs/manual/src/proc_macro/renaming.md

@@ -1,7 +1,10 @@
-# Renaming
+# Renaming via proc-macros
 
 UniFFI allows you to rename all callables and user-defined types in the foreign bindings using the `name` attribute.
 
+Renaming via proc-macros impacts all language bindings.
+For language-specific renaming, which offers renaming enum varients, record members, args, etc, see [TOML-based renaming](../renaming.md).
+
 ## Examples
 
 ### Functions:

docs/manual/src/python/configuration.md

@@ -9,6 +9,7 @@ The generated Python modules can be configured using a `uniffi.toml` configurati
 | `cdylib_name`      | `uniffi_{namespace}`[^1] | The name of the compiled Rust library containing the FFI implementation (not needed when using `generate --library`). |
 | `custom_types`      | | A map which controls how custom types are exposed to Python. See the [custom types section of the manual](../types/custom_types.md#custom-types-in-the-bindings-code)|
 | `external_packages` | | A map which controls the package name used by external packages. See below for more.
+| `rename`           | | A map to rename types, functions, methods, and their members in the generated Python bindings. See the [renaming section](../renaming.md).
 
 ## External Packages
 

docs/manual/src/renaming.md

@@ -0,0 +1,41 @@
+# Renaming
+
+UniFFI provides two ways to customize names in generated bindings:
+
+1. **Proc-macro attributes** - Use variants of `#[uniffi(name = "...")]` to rename items directly in Rust code. See [proc-macro renaming](proc_macro/renaming.md).
+2. **TOML configuration** - Define language-specific renames in `uniffi.toml`.
+
+## TOML-based Renaming
+
+You can rename types, functions, methods, constructors, and their members (fields, variants, arguments) on a per-language basis using `uniffi.toml`.
+The intended use-case here is for when a name could be made more idiomatic in one specific binding - you can rename many things unconditionally for all bindings using proc macros.
+
+An example `uniffi.toml` which is renaming Python:
+```toml
+[bindings.python.rename]
+# Rename types
+# `struct MyRecord { .. }` -> `PythonRecord`
+MyRecord = "PythonRecord"
+
+# Rename nested items using dot notation
+# `struct MyRecord { field: u32  }` -> `PythonRecord(python_field ...)`
+"MyRecord.field" = "python_field"
+"MyEnum.VariantA" = "PythonVariantA"
+"MyEnum.VariantA.int_field" = "python_field"
+
+# `fn my_function(first_arg: u8)` -> `def python_function(python_arg)`
+"my_function" = "python_function"
+"my_function.first_arg" = "python_arg"
+"MyObject.method" = "python_method"
+"MyObject.method.foo" = "python_foo"
+```
+
+The same pattern applies to all renameable items: records, record fields, enums, enum variants, enum variant fields, objects/callback interfaces/traits, and all "callables" and arguments.
+
+### Notes
+
+- Each crate defines its own rename configuration, you cannot rename types from external crates
+- uniffi normalizes names for each language (eg, `my_func` becomes `myFunc` in some languages) after the renaming is applied.
+  For example, renaming `my_func` to `renamed_func` would cause the final name to be `renamedFunc` in those languages.
+- All builtin bindings support this but external bindings may not.
+- Renaming the primary constructor "works", but will have no impact in bindings as the name isn't used.

docs/manual/src/swift/configuration.md

@@ -17,6 +17,7 @@ more likely to change than other configurations.
 | `omit_argument_labels`               | `false`                  | Whether to omit argument labels in Swift function definitions.                                                                                                                                              |
 | `generate_immutable_records`         | `false`                  | Whether to generate records with immutable fields (`let` instead of `var`).                                                                                                                                 |
 | `custom_types`                       |                          | A map which controls how custom types are exposed to Swift. See the [custom types section of the manual](../types/custom_types.md#custom-types-in-the-bindings-code)                                        |
+| `rename`                             |                          | A map to rename types, functions, methods, and their members in the generated Swift bindings. See the [renaming section](../renaming.md).                                                                   |
 | `omit_localized_error_conformance`   | `false`                  | Whether to make generated error types conform to `LocalizedError`.                                                                                                                                          |
 | `generate_case_iterable_conformance` | `false`                  | Whether to make simple generated enum and error types conform to `CaseIterable`.                                                                                                                            |
 | `generate_codable_conformance`       | `false`                  | Whether to make generated record, enum and error types conform to `Codable`.                                                                                                                                |

fixtures/ext-types/lib/src/lib.rs

@@ -5,7 +5,7 @@ use ext_types_external_crate::{
 };
 use std::sync::Arc;
 use uniffi_one::{
-    UniffiOneEnum, UniffiOneError, UniffiOneErrorInterface, UniffiOneInterface,
+    BindingRenamedType, UniffiOneEnum, UniffiOneError, UniffiOneErrorInterface, UniffiOneInterface,
     UniffiOneProcMacroType, UniffiOneTLA, UniffiOneTrait, UniffiOneType, UniffiOneUDLTrait,
 };
 use uniffi_sublib::{NotToThrowError, SubLibType};
@@ -241,4 +241,12 @@ pub struct ContainsExternalError2 {
 #[uniffi::export]
 fn takes_external_error(_error: NotToThrowError) {}
 
+// Using a type in an external crate which is renamed via toml in that crate.
+#[uniffi::export]
+fn get_binding_renamed_type(value: Option<String>) -> BindingRenamedType {
+    BindingRenamedType {
+        value: value.unwrap_or_else(|| "test_renamed_type".to_string()),
+    }
+}
+
 uniffi::include_scaffolding!("ext-types-lib");

fixtures/ext-types/lib/tests/bindings/test_imported_types.kts

@@ -81,3 +81,8 @@ try {
 
 assert(ct.ecd.sval == "ecd")
 assert(getExternalCrateInterface("foo").value() == "foo")
+
+// Test that BindingRenamedType from uniffi-one is renamed to KotlinRenamedType via direct function call
+val renamedType = getBindingRenamedType("external_rename_test")
+assert(renamedType is KotlinRenamedType)
+assert(renamedType.kotlinValue == "external_rename_test")

fixtures/ext-types/lib/tests/bindings/test_imported_types.py

@@ -105,6 +105,11 @@ def test_external_errors(self):
         with self.assertRaises(UniffiOneErrorInterface) as cm:
             throw_uniffi_one_error_interface()
 
+    def test_rename(self):
+        t = get_binding_renamed_type("external_rename_test")
+        self.assertIsInstance(t, PythonRenamedType)
+        self.assertEqual(t.python_value, "external_rename_test")
+
 if __name__=='__main__':
     test_external_callback_interface_impl()
     unittest.main()

fixtures/ext-types/lib/tests/bindings/test_imported_types.swift

@@ -98,3 +98,8 @@ do {
 
 assert(ct.ecd.sval == "ecd")
 assert(getExternalCrateInterface(val: "foo").value() == "foo")
+
+// Test that BindingRenamedType from uniffi-one is renamed to SwiftRenamedType via direct function call
+let renamedType = getBindingRenamedType(value: "external_rename_test")
+assert(renamedType == SwiftRenamedType(swiftValue: "external_rename_test"))
+assert(renamedType.swiftValue == "external_rename_test")