IMPORTANT: To view this page as Markdown, append `.md` to the URL (e.g. /docs/manual/basics.md). For the complete Mojo documentation index, see llms.txt.
Skip to main content
Version: Nightly
For the complete Mojo documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /docs/manual/basics.md).

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 (StaticString): 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, Deinitable, Movable

Methods​

__init__​

def __init__(out self, type_name: StringSpan[ImmStaticOrigin], *, basicsize: Int)

Construct a new builder for a Python type binding.

Args:

  • ​type_name (StringSpan[ImmStaticOrigin]): 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 def bind[T: Deinitable](type_name: StringSpan[ImmStaticOrigin]) -> Self

Construct a new builder for a Python type that binds a Mojo type.

Parameters:

Args:

Returns:

Self: A new type builder instance.

finalize​

def 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 def_init_defaultable[T: Defaultable & Deinitable & Movable](mut self) -> ref[self] Self

Declare a binding for the __init__ method of the type which initializes the type with a default value.

Parameters:

Returns:

ref[self] Self: A reference to self for method chaining.

Raises:

If the slot insertion fails.

def_py_init​

def def_py_init[T: Deinitable & Movable, //, init_func: def(args: PythonObject, kwargs: PythonObject) thin -> T](mut self) -> ref[self] Self

Declare a binding for the __init__ method of the type.

Parameters:

  • ​T (Deinitable & Movable): The Mojo type to bind.
  • ​init_func (def(args: PythonObject, kwargs: PythonObject) thin -> T): The initialization function to bind.

Returns:

ref[self] Self: A reference to self for method chaining.

Raises:

If the slot insertion fails.

def def_py_init[T: Deinitable & Movable, //, init_func: def(args: PythonObject, kwargs: PythonObject) raises thin -> T](mut self) -> ref[self] Self

Declare a binding for the __init__ method of the type.

Parameters:

  • ​T (Deinitable & Movable): The Mojo type to bind.
  • ​init_func (def(args: PythonObject, kwargs: PythonObject) raises thin -> T): The initialization function to bind (may raise).

Returns:

ref[self] Self: A reference to self for method chaining.

Raises:

If the slot insertion fails.

def_py_c_method​

def def_py_c_method[static_method: Bool = False](mut self, method: def(PyObjectPtr, PyObjectPtr) abi("C") thin -> PyObjectPtr, method_name: StringSpan[ImmStaticOrigin], docstring: StringSpan[ImmStaticOrigin] = StringSpan()) -> ref[self] 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 null pointer for the first argument for static methods (i.e. instead of passing the self object). See METH_STATIC.

Args:

  • ​method (def(PyObjectPtr, PyObjectPtr) abi("C") thin -> PyObjectPtr): The method to declare a binding for.
  • ​method_name (StringSpan[ImmStaticOrigin]): The name with which the method will be exposed on the type.
  • ​docstring (StringSpan[ImmStaticOrigin]): The docstring for the method of the type.

Returns:

ref[self] Self: The builder with the method binding declared.

def def_py_c_method[static_method: Bool = False](mut self, method: def(PyObjectPtr, PyObjectPtr, PyObjectPtr) abi("C") thin -> PyObjectPtr, method_name: StringSpan[ImmStaticOrigin], docstring: StringSpan[ImmStaticOrigin] = StringSpan()) -> ref[self] Self

Declare a binding for a method with PyCFunctionWithKeywords 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 null pointer for the first argument for static methods (i.e. instead of passing the self object). See METH_STATIC.

Args:

  • ​method (def(PyObjectPtr, PyObjectPtr, PyObjectPtr) abi("C") thin -> PyObjectPtr): The method to declare a binding for.
  • ​method_name (StringSpan[ImmStaticOrigin]): The name with which the method will be exposed on the type.
  • ​docstring (StringSpan[ImmStaticOrigin]): The docstring for the method of the type.

Returns:

ref[self] Self: The builder with the method binding declared.

def def_py_c_method[static_method: Bool = False](mut self, method: def(PyObjectPtr, Pointer[PyObjectPtr, MutUntrackedOrigin], Int) abi("C") thin -> PyObjectPtr, method_name: StringSpan[ImmStaticOrigin], docstring: StringSpan[ImmStaticOrigin] = StringSpan()) -> ref[self] Self

Declare a binding for a method with PyCFunctionFast signature (METH_FASTCALL) for the type.

Parameters:

  • ​static_method (Bool): Whether the method is exposed as a staticmethod. Default is False.

Args:

  • ​method (def(PyObjectPtr, Pointer[PyObjectPtr, MutUntrackedOrigin], Int) abi("C") thin -> PyObjectPtr): The fastcall method to declare a binding for.
  • ​method_name (StringSpan[ImmStaticOrigin]): The name with which the method will be exposed on the type.
  • ​docstring (StringSpan[ImmStaticOrigin]): The docstring for the method of the type.

Returns:

ref[self] Self: The builder with the method binding declared.

def_py_method​

def def_py_method[method: def(mut PythonObject, mut PythonObject) raises thin -> PythonObject, static_method: Bool = False](mut self, method_name: StringSpan[ImmStaticOrigin], docstring: StringSpan[ImmStaticOrigin] = StringSpan()) -> ref[self] Self

Declare a binding for a method with PyFunctionRaising signature.

Accepts methods with signature: def (mut PythonObject, mut PythonObject) thin raises -> PythonObject where the first arg is self and the second is a tuple of arguments.

Parameters:

  • ​method (def(mut PythonObject, mut PythonObject) raises thin -> PythonObject): The method to declare a binding for.
  • ​static_method (Bool): Whether the method is exposed as a staticmethod.

Args:

Returns:

ref[self] Self: The builder with the method binding declared.

def def_py_method[method: def(mut PythonObject, mut PythonObject, mut PythonObject) raises thin -> PythonObject, static_method: Bool = False](mut self, method_name: StringSpan[ImmStaticOrigin], docstring: StringSpan[ImmStaticOrigin] = StringSpan()) -> ref[self] Self

Declare a binding for a method with PyFunctionWithKeywordsRaising signature.

Accepts methods with signature: def (mut PythonObject, mut PythonObject, mut PythonObject) thin raises -> PythonObject where the first arg is self, the second is a tuple of arguments, and the third is a dict of keyword arguments.

Parameters:

  • ​method (def(mut PythonObject, mut PythonObject, mut PythonObject) raises thin -> PythonObject): The method to declare a binding for.
  • ​static_method (Bool): Whether the method is exposed as a staticmethod.

Args:

Returns:

ref[self] Self: The builder with the method binding declared.

def_method​

def def_method[SelfType: Deinitable, PyArgs: TypeList[PyArgs.values], RetType: Deinitable & Movable, //, method: def(self_: Pointer[SelfType, MutUnsafeAnyOrigin], *args: *PyArgs, var **kwargs: PythonObject) raises thin -> RetType](mut self, method_name: StringSpan[ImmStaticOrigin], docstring: StringSpan[ImmStaticOrigin] = StringSpan("")) -> ref[self] Self where Bool(identical(RetType, PythonObject)) or Bool(identical(RetType, None))

Declares a binding for a method with an automatically downcast self.

The method receives a pointer to the wrapped Mojo value. Methods that need generic Python object access can receive PythonObject instead.

Non-kwargs methods register through CPython's METH_FASTCALL calling convention; kwargs-accepting methods use METH_VARARGS | METH_KEYWORDS.

Example signatures:

from std.python import PythonObject

def method(
    self: Pointer[Self, MutUnsafeAnyOrigin],
    arg: PythonObject,
    var **kwargs: PythonObject,
) raises -> PythonObject: ...

Parameters:

  • ​SelfType (Deinitable): The wrapped Mojo self type.
  • ​PyArgs (TypeList[PyArgs.values]): The method's positional Python argument types.
  • ​RetType (Deinitable & Movable): The method's return type.
  • ​method (def(self_: Pointer[SelfType, MutUnsafeAnyOrigin], *args: *PyArgs, var **kwargs: PythonObject) raises thin -> RetType): The method to declare a binding for.

Args:

Returns:

ref[self] Self: The builder with the method binding declared.

def_staticmethod​

def def_staticmethod[PyArgs: TypeList[PyArgs.values], RetType: Deinitable & Movable, //, method: def(*args: *PyArgs, var **kwargs: PythonObject) raises thin -> RetType](mut self, method_name: StringSpan[ImmStaticOrigin], docstring: StringSpan[ImmStaticOrigin] = StringSpan()) -> ref[self] Self where Bool(identical(RetType, PythonObject)) or Bool(identical(RetType, None))

Declares a binding for a static method with optional keyword arguments.

Accepts methods with PythonObject positional and keyword arguments. The method can return a PythonObject or None, and can raise.

Non-kwargs static methods register through CPython's METH_FASTCALL calling convention; kwargs-accepting static methods use METH_VARARGS | METH_KEYWORDS.

Example signatures:

from std.python import PythonObject

def static_method(arg1: PythonObject) -> PythonObject: ...
def static_method(arg1: PythonObject, arg2: PythonObject) raises: ...
def static_method(
    arg: PythonObject, var **kwargs: PythonObject
) raises -> PythonObject: ...

Parameters:

  • ​method (def(*args: *PyArgs, var **kwargs: PythonObject) raises thin -> RetType): The static method to declare a binding for.

Args:

Returns:

ref[self] Self: The builder with the method binding declared.

View source