Mojo struct
PythonTypeBuilder
struct PythonTypeBuilder
A builder for a Python 'type' binding.
This is typically used to build a type description of a PyMojoObject[T].
This builder is used to declare method bindings for a Python type, and then create the type binding.
Finalizing builder created with PythonTypeObject.bind[T]() will globally
register the resulting Python 'type' object as the single canonical type
object for the Mojo type T. Subsequent attempts to register a Python type
for T will raise an exception.
Registering a Python type object for T is necessary to be able to
construct a PythonObject from an instance of T, or to downcast an
existing PythonObject to a pointer to the inner T value.
Fields
- type_name (
StringSlice[StaticConstantOrigin]): The name the type will be exposed as in the Python module. - basicsize (
Int): The required allocation size to hold an instance of this type as a Python object. - methods (
List[PyMethodDef]): List of method definitions that will be exposed on the Python type.
Implemented traits
AnyType,
Copyable,
Movable,
UnknownDestructibility
Methods
__init__
__init__(out self, type_name: StringSlice[StaticConstantOrigin], *, basicsize: Int)
Construct a new builder for a Python type binding.
Args:
- type_name (
StringSlice[StaticConstantOrigin]): The name the type will be exposed as in the Python module. - basicsize (
Int): The required allocation size to hold an instance of this type as a Python object.
bind
static bind[T: Representable](type_name: StringSlice[StaticConstantOrigin]) -> Self
Construct a new builder for a Python type that binds a Mojo type.
Parameters:
- T (
Representable): The mojo type to bind.
Args:
- type_name (
StringSlice[StaticConstantOrigin]): The name the type will be exposed as in the Python module.
Returns:
A new type builder instance.
finalize
finalize(mut self, module: PythonObject)
Finalize the builder and add the created type to a Python module.
This method completes the type building process by calling the
parameterless finalize() method to create the Python type object, then
automatically adds the resulting type to the specified Python module
using the builder's configured type name. After successful completion,
the builder's method list is cleared to prevent accidental reuse.
This is a convenience method that combines type finalization and module registration in a single operation, which is the most common use case when creating Python-accessible Mojo types.
Note:
After calling this method, the builder's internal state is modified
(methods list is cleared), so the builder should not be reused for
creating additional type objects. If you need the type object for
further operations, use the parameterless finalize() method
instead and manually add it to the module.
Args:
- module (
PythonObject): The Python module to which the finalized type will be added. The type will be accessible from Python code that imports this module using the name specified during builder construction.
Raises:
If the type object creation fails (see finalize() for details) or
if adding the type to the module fails, typically due to name
conflicts or module state issues.
def_init_defaultable
def_init_defaultable[T: Defaultable & Movable](mut self) -> ref [*[0,0]] Self
Declare a binding for the __init__ method of the type which initializes the type with a default value.
def_py_init
def_py_init[T: Movable, //, init_func: fn(args: PythonObject, kwargs: PythonObject) -> T](mut self) -> ref [*[0,0]] Self
Declare a binding for the __init__ method of the type.
def_py_init[T: Movable, //, init_func: fn(args: PythonObject, kwargs: PythonObject) raises -> T](mut self) -> ref [*[0,0]] Self
Declare a binding for the __init__ method of the type.
def_py_c_method
def_py_c_method[static_method: Bool = False](mut self, method: fn(PyObjectPtr, PyObjectPtr) -> PyObjectPtr, method_name: StringSlice[StaticConstantOrigin], docstring: StringSlice[StaticConstantOrigin] = StringSlice()) -> ref [*[0,0]] Self
Declare a binding for a method with PyObjectPtr signature for the type.
Parameters:
- static_method (
Bool): Whether the method is exposed as a staticmethod. Default is False. Note that CPython will pass a nullpointer for the first argument for static methods (i.e. instead of passing the self object). See METH_STATIC.
Args:
- method (
fn(PyObjectPtr, PyObjectPtr) -> PyObjectPtr): The method to declare a binding for. - method_name (
StringSlice[StaticConstantOrigin]): The name with which the method will be exposed on the type. - docstring (
StringSlice[StaticConstantOrigin]): The docstring for the method of the type.
Returns:
The builder with the method binding declared.
def_py_method
def_py_method[method: fn(mut PythonObject, mut PythonObject) -> PythonObject, static_method: Bool = False](mut self, method_name: StringSlice[StaticConstantOrigin], docstring: StringSlice[StaticConstantOrigin] = StringSlice()) -> ref [*[0,0]] Self
Declare a binding for a method with PyFunction signature.
Accepts methods with signature: fn (mut PythonObject, mut PythonObject) -> PythonObject
where the first arg is self and the second is a tuple of arguments.
Parameters:
- method (
fn(mut PythonObject, mut PythonObject) -> PythonObject): The method to declare a binding for. - static_method (
Bool): Whether the method is exposed as a staticmethod. Default is False. Note that CPython will pass a nullpointer for the first argument for static methods (i.e. instead of passing the self object). See METH_STATIC.
Args:
- method_name (
StringSlice[StaticConstantOrigin]): The name with which the method will be exposed on the type. - docstring (
StringSlice[StaticConstantOrigin]): The docstring for the method of the type.
Returns:
The builder with the method binding declared.
def_py_method[method: fn(mut PythonObject, mut PythonObject) raises -> PythonObject, static_method: Bool = False](mut self, method_name: StringSlice[StaticConstantOrigin], docstring: StringSlice[StaticConstantOrigin] = StringSlice()) -> ref [*[0,0]] Self
Declare a binding for a method with PyFunctionRaising signature.
Accepts methods with signature: fn (mut PythonObject, mut PythonObject) raises -> PythonObject
where the first arg is self and the second is a tuple of arguments.
Parameters:
- method (
fn(mut PythonObject, mut PythonObject) raises -> PythonObject): The method to declare a binding for. - static_method (
Bool): Whether the method is exposed as a staticmethod.
Args:
- method_name (
StringSlice[StaticConstantOrigin]): The name with which the method will be exposed on the type. - docstring (
StringSlice[StaticConstantOrigin]): The docstring for the method of the type.
Returns:
The builder with the method binding declared.
def_method
def_method[method_type: AnyTrivialRegType, //, method: PyObjectFunction[method_type, PythonObject]](mut self, method_name: StringSlice[StaticConstantOrigin], docstring: StringSlice[StaticConstantOrigin] = StringSlice()) -> ref [*[0,0]] Self
Declare a binding for a method that receives self as PythonObject.
Use this when you need generic Python object access. For direct access to the wrapped
Mojo type, use the typed self def_method overload instead.
Example signatures:
fn method(mut self: PythonObject) -> PythonObject
fn method(mut self: PythonObject, arg1: PythonObject) raises
fn method(mut self: PythonObject) -> PythonObject
fn method(mut self: PythonObject, arg1: PythonObject) raises
Parameters:
- method_type (
AnyTrivialRegType): The type of the method to declare a binding for. - method (
PyObjectFunction[method_type, PythonObject]): The method to declare a binding for. Users can pass their function directly, and it will be implicitly converted to a PyObjectFunction if and only if its signature is supported.
Args:
- method_name (
StringSlice[StaticConstantOrigin]): The name with which the method will be exposed on the type. - docstring (
StringSlice[StaticConstantOrigin]): The docstring for the method of the type.
Returns:
The builder with the method binding declared.
def_method[method_self: AnyType, method_type: AnyTrivialRegType, //, method: PyObjectFunction[method_type, method_self]](mut self, method_name: StringSlice[StaticConstantOrigin], docstring: StringSlice[StaticConstantOrigin] = StringSlice()) -> ref [*[0,0]] Self
Declare a binding for a method that takes a typed self as first argument.
This method automatically handles the downcasting of the Python self object
to the specified Mojo type. To receive a generic PythonObject as self, use
the generic self def_method overload instead.
Example usage:
fn my_method(self: UnsafePointer[Self], arg: PythonObject) -> PythonObject
fn my_method(self: UnsafePointer[Self], arg: PythonObject) -> PythonObject
Parameters:
- method_self (
AnyType): The type of the self parameter (inferred from the method). - method_type (
AnyTrivialRegType): The type signature of the method to declare a binding for. - method (
PyObjectFunction[method_type, method_self]): The method to declare a binding for. The first parameter should be the typed self parameter.
Args:
- method_name (
StringSlice[StaticConstantOrigin]): The name with which the method will be exposed on the type. - docstring (
StringSlice[StaticConstantOrigin]): The docstring for the method of the type.
Returns:
The builder with the method binding declared.
def_staticmethod
def_staticmethod[method_type: AnyTrivialRegType, //, method: PyObjectFunction[method_type]](mut self, method_name: StringSlice[StaticConstantOrigin], docstring: StringSlice[StaticConstantOrigin] = StringSlice()) -> ref [*[0,0]] Self
Declare a binding for a static method (no self parameter).
Accepts functions with PythonObject arguments (up to 6), can optionally return a PythonObject, and can raise.
Example signatures:
fn static_method(arg1: PythonObject) -> PythonObject
fn static_method(arg1: PythonObject, arg2: PythonObject) raises
fn static_method(arg1: PythonObject) -> PythonObject
fn static_method(arg1: PythonObject, arg2: PythonObject) raises
Parameters:
- method_type (
AnyTrivialRegType): The type of the method to declare a binding for. - method (
PyObjectFunction[method_type]): The method to declare a binding for. Users can pass their function directly, and it will be implicitly converted to a PyObjectFunction if and only if its signature is supported.
Args:
- method_name (
StringSlice[StaticConstantOrigin]): The name with which the method will be exposed on the type. - docstring (
StringSlice[StaticConstantOrigin]): The docstring for the method of the type.
Returns:
The builder with the method binding declared.
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!