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: Movable & Defaultable & Representable](type_name: StringSlice[StaticConstantOrigin]) -> Self
Construct a new builder for a Python type that binds a Mojo type.
Parameters:
- T (
Movable & Defaultable & 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_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 PyObject signature for the type.
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 PyObject signature for the type.
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, True]](mut self, method_name: StringSlice[StaticConstantOrigin], docstring: StringSlice[StaticConstantOrigin] = StringSlice()) -> ref [*[0,0]] Self
Declare a binding for a method with PythonObject signature for the type.
These signatures can have any number of positional PythonObject arguments up to 6 (including self), can optionally return a PythonObject, and can raise.
Example signature types:
alias F1 = fn (mut PythonObject) raises -> PythonObject
alias F2 = fn (mut PythonObject, PythonObject) -> PythonObject
alias F3 = fn (mut PythonObject, PythonObject, mut PythonObject)
alias F1 = fn (mut PythonObject) raises -> PythonObject
alias F2 = fn (mut PythonObject, PythonObject) -> PythonObject
alias F3 = fn (mut PythonObject, PythonObject, mut PythonObject)
Parameters:
- method_type (
AnyTrivialRegType): The type of the method to declare a binding for. - method (
PyObjectFunction[method_type, True]): 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_staticmethod
def_staticmethod[method_type: AnyTrivialRegType, //, method: PyObjectFunction[method_type, False]](mut self, method_name: StringSlice[StaticConstantOrigin], docstring: StringSlice[StaticConstantOrigin] = StringSlice()) -> ref [*[0,0]] Self
Declare a binding for a staticmethod with PythonObject signature for the type.
These signatures can have any number of positional PythonObject arguments up to 6, can optionally return a PythonObject, and can raise.
Example signature types:
alias F1 = fn (mut PythonObject) raises -> PythonObject
alias F2 = fn (mut PythonObject, PythonObject) -> PythonObject
alias F3 = fn (mut PythonObject, PythonObject, mut PythonObject)
alias F1 = fn (mut PythonObject) raises -> PythonObject
alias F2 = fn (mut PythonObject, PythonObject) -> PythonObject
alias F3 = fn (mut PythonObject, PythonObject, mut PythonObject)
Parameters:
- method_type (
AnyTrivialRegType): The type of the method to declare a binding for. - method (
PyObjectFunction[method_type, False]): 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!