Skip to content

Configuration

The generated Python modules can be configured using a uniffi.toml configuration file.

Available options

Configuration name Default Description
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
external_packages A map which controls the package name used by external packages. See below for more.

External Packages

When you reference external modules, uniffi will generate statements like from module import Type in the referencing module. The external_packages configuration value allows you to specify how module is formed in such statements.

The value is a map, keyed by the crate-name and the value is the package name which will be used by Python for that crate. The default value is an empty map.

When looking up crate-name, the following behavior is implemented.

Default value

If no value for the crate is found, it is assumed that you will be packaging up your library as a simple Python package, so the statement will be of the form from .module import Type, where module is the namespace specified in that crate.

Note that this is invalid syntax unless the module lives in a package - attempting to use the module as a stand-alone module will fail. UniFFI just generates flat .py files; the packaging is up to you. Eg, a build process might create a directory, create an __init__.py file in that directory (maybe including from subpackage import *) and have uniffi-bindgen generate the bindings into this directory.

Specified value

If the crate-name is found in the map, the specified entry used as a package name, so the statement will be of the form from package.module import Type (again, where module is the namespace specified in that crate)

An exception is when the specified value is an empty string, in which case you will see from module import Type, so each generated module functions outside a package. This is used by some UniFFI tests to avoid the test code needing to create a Python package.

Examples

Custom Types

# Assuming a Custom Type named URL using a String as the builtin.
[bindings.python.custom_types.Url]
imports = ["urllib.parse"]
# Functions to convert between strings and the ParsedUrl class
into_custom = "urllib.parse.urlparse({})"
from_custom = "urllib.parse.urlunparse({})"

External Packages

[bindings.python.external_packages]
# An external type `Foo` in `crate-name` (which specifies a namespace of `my_module`) will be referenced via `from MyPackageName.my_module import Foo`
crate-name = "MyPackageName"