Mojo struct

PythonObject

@register_passable struct PythonObject

A Python object.

Implemented traits

AnyType, Boolable, ConvertibleToPython, Copyable, Defaultable, Identifiable, ImplicitlyCopyable, Movable, SizedRaising, UnknownDestructibility, Writable

Aliases

`copyinitis_trivial`

alias __copyinit__is_trivial = False

`delis_trivial`

alias __del__is_trivial = False

`moveinitis_trivial`

alias __moveinit__is_trivial = PyObjectPtr.__moveinit__is_trivial

Methods

`init`

__init__() -> Self

Initialize the object with a None value.

__init__(*, from_owned: PyObjectPtr) -> Self

Initialize this object from an owned reference-counted Python object pointer.

For example, this function should be used to construct a PythonObject from the pointer returned by "New reference"-type objects from the CPython API.

References:

https://docs.python.org/3/glossary.html#term-strong-reference

Args:

from_owned (PyObjectPtr): An owned pointer to a Python object.

__init__(*, from_borrowed: PyObjectPtr) -> Self

Initialize this object from a borrowed reference-counted Python object pointer.

For example, this function should be used to construct a PythonObject from the pointer returned by "Borrowed reference"-type objects from the CPython API.

References:

https://docs.python.org/3/glossary.html#term-borrowed-reference

Args:

from_borrowed (PyObjectPtr): A borrowed pointer to a Python object.

__init__[T: Movable](out self, *, var alloc: T)

Allocate a new PythonObject and store a Mojo value in it.

The newly allocated Python object will contain the provided Mojo T instance directly, without attempting conversion to an equivalent Python builtin type.

Only Mojo types that have a registered Python 'type' object can be stored as a Python object. Mojo types are registered using a PythonTypeBuilder.

Parameters:

T (Movable): The Mojo type of the value that the resulting Python object holds.

Args:

alloc (T): The Mojo value to store in the new Python object.

Raises:

If no Python type object has been registered for T by a PythonTypeBuilder.

@implicit __init__(none: NoneType) -> Self

Initialize a none value object from a None literal.

Args:

none (NoneType): None.

@implicit __init__(value: Bool) -> Self

Initialize the object from a bool.

Args:

value (Bool): The boolean value.

@implicit __init__(value: Int) -> Self

Initialize the object with an integer value.

Args:

value (Int): The integer value.

@implicit __init__[dtype: DType](value: Scalar[dtype]) -> Self

Initialize the object with a generic scalar value. If the scalar value type is bool, it is converted to a boolean. Otherwise, it is converted to the appropriate integer or floating point type.

Parameters:

dtype (DType): The scalar value type.

Args:

value (Scalar): The scalar value.

@implicit __init__(out self, string: StringSlice[origin])

Initialize the object from a string.

Args:

string (StringSlice): The string value.

Raises:

If the string is not valid UTF-8.

@implicit __init__(out self, value: StringLiteral[value])

Initialize the object from a string literal.

Args:

value (StringLiteral): The string literal value.

@implicit __init__(out self, value: String)

Initialize the object from a string.

Args:

value (String): The string value.

@implicit __init__(slice: Slice) -> Self

Initialize the object from a Mojo Slice.

Args:

slice (Slice): The dictionary value.

__init__[*Ts: ConvertibleToPython & Copyable](out self, var *values: *Ts, *, __list_literal__: Tuple[])

Construct an Python list of objects.

Parameters:

*Ts (ConvertibleToPython & Copyable): The types of the input values.

Args:

*values (*Ts): The values to initialize the list with.
list_literal (Tuple): Tell Mojo to use this method for list literals.

Returns:

Self: The constructed Python list.

__init__[*Ts: ConvertibleToPython & Copyable](out self, var *values: *Ts, *, __set_literal__: Tuple[])

Construct an Python set of objects.

Parameters:

*Ts (ConvertibleToPython & Copyable): The types of the input values.

Args:

*values (*Ts): The values to initialize the set with.
set_literal (Tuple): Tell Mojo to use this method for set literals.

Returns:

Self: The constructed Python set.

__init__(out self, var keys: List[PythonObject], var values: List[PythonObject], __dict_literal__: Tuple[])

Construct a Python dictionary from a list of keys and a list of values.

Args:

keys (List): The keys of the dictionary.
values (List): The values of the dictionary.
dict_literal (Tuple): Tell Mojo to use this method for dict literals.

`copyinit`

__copyinit__(existing: Self) -> Self

Copy the object.

This increments the underlying refcount of the existing object.

Args:

existing (Self): The value to copy.

`del`

__del__(var self)

Destroy the object.

This decrements the underlying refcount of the pointed-to object.

`bool`

__bool__(self) -> Bool

Evaluate the boolean value of the object.

Returns:

Bool: Whether the object evaluates as true.

`getitem`

__getitem__(self, *args: Self) -> Self

Return the value for the given key or keys.

Args:

*args (Self): The key or keys to access on this object.

Returns:

Self: The value corresponding to the given key for this object.

__getitem__(self, *args: Slice) -> Self

Return the sliced value for the given Slice or Slices.

Args:

*args (Slice): The Slice or Slices to apply to this object.

Returns:

Self: The sliced value corresponding to the given Slice(s) for this object.

`setitem`

__setitem__(self, *args: Self, *, value: Self)

Set the value with the given key or keys.

Args:

*args (Self): The key or keys to set on this object.
value (Self): The value to set.

`neg`

__neg__(self) -> Self

Negative.

Calls the underlying object's __neg__ method.

Returns:

Self: The result of prefixing this object with a - operator. For most numerical objects, this returns the negative.

`pos`

__pos__(self) -> Self

Positive.

Calls the underlying object's __pos__ method.

Returns:

Self: The result of prefixing this object with a + operator. For most numerical objects, this does nothing.

`invert`

__invert__(self) -> Self

Inversion.

Calls the underlying object's __invert__ method.

Returns:

Self: The logical inverse of this object: a bitwise representation where all bits are flipped, from zero to one, and from one to zero.

`lt`

__lt__(self, rhs: Self) -> Self

Less than (rich) comparison operator.

Args:

rhs (Self): The value of the right hand side of the comparison.

Returns:

Self: The result of the comparison, not necessarily a boolean.

Raises:

If the object doesn't implement the __lt__ method, or if it fails.

`le`

__le__(self, rhs: Self) -> Self

Less than or equal (rich) comparison operator.

Args:

rhs (Self): The value of the right hand side of the comparison.

Returns:

Self: The result of the comparison, not necessarily a boolean.

Raises:

If the object doesn't implement the __le__ method, or if it fails.

`eq`

__eq__(self, rhs: Self) -> Self

Equality (rich) comparison operator.

Args:

rhs (Self): The value of the right hand side of the comparison.

Returns:

Self: The result of the comparison, not necessarily a boolean.

Raises:

If the object doesn't implement the __eq__ method, or if it fails.

`ne`

__ne__(self, rhs: Self) -> Self

Inequality (rich) comparison operator.

Args:

rhs (Self): The value of the right hand side of the comparison.

Returns:

Self: The result of the comparison, not necessarily a boolean.

Raises:

If the object doesn't implement the __ne__ method, or if it fails.

`gt`

__gt__(self, rhs: Self) -> Self

Greater than (rich) comparison operator.

Args:

rhs (Self): The value of the right hand side of the comparison.

Returns:

Self: The result of the comparison, not necessarily a boolean.

Raises:

If the object doesn't implement the __gt__ method, or if it fails.

`ge`

__ge__(self, rhs: Self) -> Self

Greater than or equal (rich) comparison operator.

Args:

rhs (Self): The value of the right hand side of the comparison.

Returns:

Self: The result of the comparison, not necessarily a boolean.

Raises:

If the object doesn't implement the __ge__ method, or if it fails.

`is`

__is__(self, other: Self) -> Bool

Test if the PythonObject is the other PythonObject, the same as x is y in Python.

Args:

other (Self): The right-hand-side value in the comparison.

Returns:

Bool: True if they are the same object and False otherwise.

`contains`

__contains__(self, rhs: Self) -> Bool

Contains dunder.

Calls the underlying object's __contains__ method.

Args:

rhs (Self): Right hand value.

Returns:

Bool: True if rhs is in self.

`add`

__add__(self, rhs: Self) -> Self

Addition and concatenation.

Calls the underlying object's __add__ method.

Args:

rhs (Self): Right hand value.

Returns:

Self: The sum or concatenated values.

`sub`

__sub__(self, rhs: Self) -> Self

Subtraction.

Calls the underlying object's __sub__ method.

Args:

rhs (Self): Right hand value.

Returns:

Self: The difference.

`mul`

__mul__(self, rhs: Self) -> Self

Multiplication.

Calls the underlying object's __mul__ method.

Args:

rhs (Self): Right hand value.

Returns:

Self: The product.

`truediv`

__truediv__(self, rhs: Self) -> Self

Division.

Calls the underlying object's __truediv__ method.

Args:

rhs (Self): The right-hand-side value by which this object is divided.

Returns:

Self: The result of dividing the right-hand-side value by this.

`floordiv`

__floordiv__(self, rhs: Self) -> Self

Return the division of self and rhs rounded down to the nearest integer.

Calls the underlying object's __floordiv__ method.

Args:

rhs (Self): The right-hand-side value by which this object is divided.

Returns:

Self: The result of dividing this by the right-hand-side value, modulo any remainder.

`mod`

__mod__(self, rhs: Self) -> Self

Return the remainder of self divided by rhs.

Calls the underlying object's __mod__ method.

Args:

rhs (Self): The value to divide on.

Returns:

Self: The remainder of dividing self by rhs.

`pow`

__pow__(self, exp: Self) -> Self

Raises this object to the power of the given value.

Args:

exp (Self): The exponent.

Returns:

Self: The result of raising this by the given exponent.

`lshift`

__lshift__(self, rhs: Self) -> Self

Bitwise left shift.

Args:

rhs (Self): The right-hand-side value by which this object is bitwise shifted to the left.

Returns:

Self: This value, shifted left by the given value.

`rshift`

__rshift__(self, rhs: Self) -> Self

Bitwise right shift.

Args:

rhs (Self): The right-hand-side value by which this object is bitwise shifted to the right.

Returns:

Self: This value, shifted right by the given value.

`and`

__and__(self, rhs: Self) -> Self

Bitwise AND.

Args:

rhs (Self): The right-hand-side value with which this object is bitwise AND'ed.

Returns:

Self: The bitwise AND result of this and the given value.

`or`

__or__(self, rhs: Self) -> Self

Bitwise OR.

Args:

rhs (Self): The right-hand-side value with which this object is bitwise OR'ed.

Returns:

Self: The bitwise OR result of this and the given value.

`xor`

__xor__(self, rhs: Self) -> Self

Exclusive OR.

Args:

rhs (Self): The right-hand-side value with which this object is exclusive OR'ed.

Returns:

Self: The exclusive OR result of this and the given value.

`radd`

__radd__(self, lhs: Self) -> Self

Reverse addition and concatenation.

Calls the underlying object's __radd__ method.

Args:

lhs (Self): The left-hand-side value to which this object is added or concatenated.

Returns:

Self: The sum.

`rsub`

__rsub__(self, lhs: Self) -> Self

Reverse subtraction.

Calls the underlying object's __rsub__ method.

Args:

lhs (Self): The left-hand-side value from which this object is subtracted.

Returns:

Self: The result of subtracting this from the given value.

`rmul`

__rmul__(self, lhs: Self) -> Self

Reverse multiplication.

Calls the underlying object's __rmul__ method.

Args:

lhs (Self): The left-hand-side value that is multiplied by this object.

Returns:

Self: The product of the multiplication.

`rtruediv`

__rtruediv__(self, lhs: Self) -> Self

Reverse division.

Calls the underlying object's __rtruediv__ method.

Args:

lhs (Self): The left-hand-side value that is divided by this object.

Returns:

Self: The result of dividing the given value by this.

`rfloordiv`

__rfloordiv__(self, lhs: Self) -> Self

Reverse floor division.

Calls the underlying object's __rfloordiv__ method.

Args:

lhs (Self): The left-hand-side value that is divided by this object.

Returns:

Self: The result of dividing the given value by this, modulo any remainder.

`rmod`

__rmod__(self, lhs: Self) -> Self

Reverse modulo.

Calls the underlying object's __rmod__ method.

Args:

lhs (Self): The left-hand-side value that is divided by this object.

Returns:

Self: The remainder from dividing the given value by this.

`rpow`

__rpow__(self, lhs: Self) -> Self

Reverse power of.

Args:

lhs (Self): The number that is raised to the power of this object.

Returns:

Self: The result of raising the given value by this exponent.

`rlshift`

__rlshift__(self, lhs: Self) -> Self

Reverse bitwise left shift.

Args:

lhs (Self): The left-hand-side value that is bitwise shifted to the left by this object.

Returns:

Self: The given value, shifted left by this.

`rrshift`

__rrshift__(self, lhs: Self) -> Self

Reverse bitwise right shift.

Args:

lhs (Self): The left-hand-side value that is bitwise shifted to the right by this object.

Returns:

Self: The given value, shifted right by this.

`rand`

__rand__(self, lhs: Self) -> Self

Reverse bitwise and.

Args:

lhs (Self): The left-hand-side value that is bitwise AND'ed with this object.

Returns:

Self: The bitwise AND result of the given value and this.

`ror`

__ror__(self, lhs: Self) -> Self

Reverse bitwise OR.

Args:

lhs (Self): The left-hand-side value that is bitwise OR'ed with this object.

Returns:

Self: The bitwise OR result of the given value and this.

`rxor`

__rxor__(self, lhs: Self) -> Self

Reverse exclusive OR.

Args:

lhs (Self): The left-hand-side value that is exclusive OR'ed with this object.

Returns:

Self: The exclusive OR result of the given value and this.

`iadd`

__iadd__(mut self, rhs: Self)

Immediate addition and concatenation.

Args:

rhs (Self): The right-hand-side value that is added to this object.

`isub`

__isub__(mut self, rhs: Self)

Immediate subtraction.

Args:

rhs (Self): The right-hand-side value that is subtracted from this object.

`imul`

__imul__(mut self, rhs: Self)

In-place multiplication.

Calls the underlying object's __imul__ method.

Args:

rhs (Self): The right-hand-side value by which this object is multiplied.

`itruediv`

__itruediv__(mut self, rhs: Self)

Immediate division.

Args:

rhs (Self): The value by which this object is divided.

`ifloordiv`

__ifloordiv__(mut self, rhs: Self)

Immediate floor division.

Args:

rhs (Self): The value by which this object is divided.

`imod`

__imod__(mut self, rhs: Self)

Immediate modulo.

Args:

rhs (Self): The right-hand-side value that is used to divide this object.

`ipow`

__ipow__(mut self, rhs: Self)

Immediate power of.

Args:

rhs (Self): The exponent.

`ilshift`

__ilshift__(mut self, rhs: Self)

Immediate bitwise left shift.

Args:

rhs (Self): The right-hand-side value by which this object is bitwise shifted to the left.

`irshift`

__irshift__(mut self, rhs: Self)

Immediate bitwise right shift.

Args:

rhs (Self): The right-hand-side value by which this object is bitwise shifted to the right.

`iand`

__iand__(mut self, rhs: Self)

Immediate bitwise AND.

Args:

rhs (Self): The right-hand-side value with which this object is bitwise AND'ed.

`ixor`

__ixor__(mut self, rhs: Self)

Immediate exclusive OR.

Args:

rhs (Self): The right-hand-side value with which this object is exclusive OR'ed.

`ior`

__ior__(mut self, rhs: Self)

Immediate bitwise OR.

Args:

rhs (Self): The right-hand-side value with which this object is bitwise OR'ed.

`iter`

__iter__(self) -> _PyIter

Iterate over the object.

Returns:

_PyIter: An iterator object.

Raises:

If the object is not iterable.

`getattr`

__getattr__(self, var name: String) -> Self

Return the value of the object attribute with the given name.

Args:

name (String): The name of the object attribute to return.

Returns:

Self: The value of the object attribute with the given name.

`setattr`

__setattr__(self, var name: String, new_value: Self)

Set the given value for the object attribute with the given name.

Args:

name (String): The name of the object attribute to set.
new_value (Self): The new value to be set for that attribute.

`call`

__call__(self, *args: Self, *, var **kwargs: Self) -> Self

Call the underlying object as if it were a function.

Args:

*args (Self): Positional arguments to the function.
**kwargs (Self): Keyword arguments to the function.

Returns:

Self: The return value from the called object. Raises:

If the function cannot be called for any reason.

`len`

__len__(self) -> Int

Returns the length of the object.

Returns:

Int: The length of the object.

`hash`

__hash__(self) -> Int

Returns the hash value of the object.

Returns:

Int: The hash value of the object.

`int`

__int__(self) -> Self

Convert the PythonObject to a Python int (i.e. arbitrary precision integer).

Returns:

Self: A Python int object.

Raises:

An error if the conversion failed.

`float`

__float__(self) -> Self

Convert the PythonObject to a Python float object.

Returns:

Self: A Python float object.

Raises:

If the conversion fails.

`str`

__str__(self) -> Self

Convert the PythonObject to a Python str.

Returns:

Self: A Python str object.

Raises:

An error if the conversion failed.

`write_to`

write_to(self, mut writer: T)

Formats this Python object to the provided Writer.

Args:

writer (T): The object to write to.

`to_python_object`

to_python_object(var self) -> Self

Convert this value to a PythonObject.

Returns:

Self: A PythonObject representing the value.

`steal_data`

steal_data(var self) -> PyObjectPtr

Take ownership of the underlying pointer from the Python object.

Returns:

PyObjectPtr: The underlying data.

`unsafe_get_as_pointer`

unsafe_get_as_pointer[dtype: DType](self) -> UnsafePointer[Scalar[dtype]]

Reinterpret a Python integer as a Mojo pointer.

Warning: converting from an integer to a pointer is unsafe! The compiler assumes the resulting pointer DOES NOT alias any Mojo-derived pointer. This is OK if the pointer originates from and is owned by Python, e.g. the data underpinning a torch tensor.

Parameters:

dtype (DType): The desired DType of the pointer.

Returns:

UnsafePointer: An UnsafePointer for the underlying Python data.

`downcast_value_ptr`

downcast_value_ptr[T: AnyType](self, *, func: Optional[StringSlice[StaticConstantOrigin]] = None) -> UnsafePointer[T]

Get a pointer to the expected contained Mojo value of type T.

This method validates that this object actually contains an instance of T, and will raise an error if it does not.

Mojo values are stored as Python objects backed by the PyMojoObject[T] struct.

Parameters:

T (AnyType): The type of the Mojo value that this Python object is expected to contain.

Args:

func (Optional): Optional name of bound Mojo function that the raised TypeError should reference if downcasting fails.

Returns:

UnsafePointer: A pointer to the inner Mojo value.

Raises:

If the Python object does not contain an instance of the Mojo T type.

`unchecked_downcast_value_ptr`

unchecked_downcast_value_ptr[T: AnyType](self) -> UnsafePointer[T]

Get a pointer to the expected Mojo value of type T.

This function assumes that this Python object was allocated as an instance of PyMojoObject[T] and that the Mojo value has been initialized.

Safety

The user must be certain that this Python object type matches the bound Python type object for T.

Parameters:

T (AnyType): The type of the Mojo value stored in this object.

Returns:

UnsafePointer: A pointer to the inner Mojo value.

View source

Was this page helpful?

Thank you! We'll create more content like this.

Thank you for helping us improve!

Implemented traits​

Aliases​

__copyinit__is_trivial​

__del__is_trivial​

__moveinit__is_trivial​

Methods​

__init__​

__copyinit__​

__del__​

__bool__​

__getitem__​

__setitem__​

__neg__​

__pos__​

__invert__​

__lt__​

__le__​

__eq__​

__ne__​

__gt__​

__ge__​

__is__​

__contains__​

__add__​

__sub__​

__mul__​

__truediv__​

__floordiv__​

__mod__​

__pow__​

__lshift__​

__rshift__​

__and__​

__or__​

__xor__​

__radd__​

__rsub__​

__rmul__​

__rtruediv__​

__rfloordiv__​

__rmod__​

__rpow__​

__rlshift__​

__rrshift__​

__rand__​

__ror__​

__rxor__​

__iadd__​

__isub__​

__imul__​

__itruediv__​

__ifloordiv__​

__imod__​

__ipow__​

__ilshift__​

__irshift__​

__iand__​

__ixor__​

__ior__​

__iter__​

__getattr__​

__setattr__​

__call__​

__len__​

__hash__​

__int__​

__float__​

__str__​

write_to​

to_python_object​

steal_data​

unsafe_get_as_pointer​

downcast_value_ptr​

unchecked_downcast_value_ptr​

Safety

Implemented traits

Aliases

`copyinitis_trivial`

`delis_trivial`

`moveinitis_trivial`

Methods

`init`

`copyinit`

`del`

`bool`

`getitem`

`setitem`

`neg`

`pos`

`invert`

`lt`

`le`

`eq`

`ne`

`gt`

`ge`

`is`

`contains`

`add`

`sub`

`mul`

`truediv`

`floordiv`

`mod`

`pow`

`lshift`

`rshift`

`and`

`or`

`xor`

`radd`

`rsub`

`rmul`

`rtruediv`

`rfloordiv`

`rmod`

`rpow`

`rlshift`

`rrshift`

`rand`

`ror`

`rxor`

`iadd`

`isub`

`imul`

`itruediv`

`ifloordiv`

`imod`

`ipow`

`ilshift`

`irshift`

`iand`

`ixor`

`ior`

`iter`

`getattr`

`setattr`

`call`

`len`

`hash`

`int`

`float`

`str`

`write_to`

`to_python_object`

`steal_data`

`unsafe_get_as_pointer`

`downcast_value_ptr`

`unchecked_downcast_value_ptr`