Skip to main content
Version: 1.0

PythonObject

struct PythonObject

A Python object.

Implemented traits​

AnyType, Boolable, ConvertibleToPython, Copyable, Defaultable, Identifiable, ImplicitlyCopyable, ImplicitlyDestructible, Movable, RegisterPassable, SizedRaising, Writable

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:

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:

Args:

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

__init__[T: Movable & ImplicitlyDestructible](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:

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.

__init__(none: NoneType) -> Self

Initialize a none value object from a None literal.

Args:

@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[string.origin])

Initialize the object from a string.

Args:

Raises:

If the string is not valid UTF-8.

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

Initialize the object from a string literal.

Args:

Raises:

If the string is not valid UTF-8.

@implicit __init__(out self, value: String)

Initialize the object from a string.

Args:

  • ​value (String): The string value.

Raises:

If the string is not valid UTF-8.

@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.values, *, __list_literal__: Tuple)

Construct an Python list of objects.

Parameters:

Args:

  • ​*values (*Ts.values): 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.

Raises:

If the list construction fails.

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

Construct an Python set of objects.

Parameters:

Args:

  • ​*values (*Ts.values): 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.

Raises:

If adding an element to the set fails.

__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.

Raises:

If setting a dictionary item fails.

__init__(*, copy: Self) -> Self

Copy the object.

This increments the underlying refcount of the existing object.

Args:

  • ​copy (Self): The value to copy.

__del__​

__del__(deinit 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.

Raises:

If the index is out of bounds or the key does not exist.

__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.

Raises:

If the index is out of bounds or the key does not exist.

__setitem__​

__setitem__[*Ks: ConvertibleToPython & Copyable, *, V: ConvertibleToPython](self, *args: *Ks.values, *, var value: V)

Set the value with the given key or keys.

Parameters:

Args:

  • ​*args (*Ks.values): The key or keys to set on this object.
  • ​value (V): The value to set.

Raises:

If setting the item fails.

__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.

Raises:

If the call fails.

__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.

Raises:

If the operation fails.

__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.

Raises:

If the call fails.

__lt__​

__lt__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Less than (rich) comparison operator.

Parameters:

Args:

  • ​rhs (T): 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__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Less than or equal (rich) comparison operator.

Parameters:

Args:

  • ​rhs (T): 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__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Equality (rich) comparison operator.

Parameters:

Args:

  • ​rhs (T): 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__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Inequality (rich) comparison operator.

Parameters:

Args:

  • ​rhs (T): 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__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Greater than (rich) comparison operator.

Parameters:

Args:

  • ​rhs (T): 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__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Greater than or equal (rich) comparison operator.

Parameters:

Args:

  • ​rhs (T): 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__[RHS: ConvertibleToPython, //](self, var rhs: RHS) -> Bool

Contains dunder.

Calls the underlying object's __contains__ method.

Parameters:

  • ​RHS (ConvertibleToPython): Type of value that can be converted to PythonObject to check for membership.

Args:

  • ​rhs (RHS): Right hand value.

Returns:

Bool: True if rhs is in self.

Raises:

If the operation fails.

__add__​

__add__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Addition and concatenation.

Calls the underlying object's __add__ method.

Parameters:

Args:

  • ​rhs (T): Right hand value.

Returns:

Self: The sum or concatenated values.

Raises:

If the operation is not supported.

__sub__​

__sub__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Subtraction.

Calls the underlying object's __sub__ method.

Parameters:

Args:

  • ​rhs (T): Right hand value.

Returns:

Self: The difference.

Raises:

If the operation is not supported.

__mul__​

__mul__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Multiplication.

Calls the underlying object's __mul__ method.

Parameters:

Args:

  • ​rhs (T): Right hand value.

Returns:

Self: The product.

Raises:

If the operation is not supported.

__truediv__​

__truediv__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Division.

Calls the underlying object's __truediv__ method.

Parameters:

Args:

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

Returns:

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

Raises:

If the operation fails.

__floordiv__​

__floordiv__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

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

Calls the underlying object's __floordiv__ method.

Parameters:

Args:

  • ​rhs (T): 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.

Raises:

If the operation fails.

__mod__​

__mod__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Return the remainder of self divided by rhs.

Calls the underlying object's __mod__ method.

Parameters:

Args:

  • ​rhs (T): The value to divide on.

Returns:

Self: The remainder of dividing self by rhs.

Raises:

If the operation fails.

__pow__​

__pow__[T: ConvertibleToPython, //](self, var exp: T) -> Self

Raises this object to the power of the given value.

Parameters:

Args:

  • ​exp (T): The exponent.

Returns:

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

Raises:

If the operation fails.

__lshift__​

__lshift__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Bitwise left shift.

Parameters:

Args:

  • ​rhs (T): 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.

Raises:

If the operation fails.

__rshift__​

__rshift__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Bitwise right shift.

Parameters:

Args:

  • ​rhs (T): 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.

Raises:

If the operation fails.

__and__​

__and__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Bitwise AND.

Parameters:

Args:

  • ​rhs (T): 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.

Raises:

If the operation fails.

__or__​

__or__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Bitwise OR.

Parameters:

Args:

  • ​rhs (T): 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.

Raises:

If the operation fails.

__xor__​

__xor__[T: ConvertibleToPython, //](self, var rhs: T) -> Self

Exclusive OR.

Parameters:

Args:

  • ​rhs (T): 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.

Raises:

If the operation fails.

__radd__​

__radd__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse addition and concatenation.

Calls the underlying object's __radd__ method.

Parameters:

Args:

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

Returns:

Self: The sum.

Raises:

If the operation is not supported.

__rsub__​

__rsub__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse subtraction.

Calls the underlying object's __rsub__ method.

Parameters:

Args:

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

Returns:

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

Raises:

If the operation is not supported.

__rmul__​

__rmul__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse multiplication.

Calls the underlying object's __rmul__ method.

Parameters:

Args:

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

Returns:

Self: The product of the multiplication.

Raises:

If the operation is not supported.

__rtruediv__​

__rtruediv__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse division.

Calls the underlying object's __rtruediv__ method.

Parameters:

Args:

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

Returns:

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

Raises:

If the operation fails.

__rfloordiv__​

__rfloordiv__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse floor division.

Calls the underlying object's __rfloordiv__ method.

Parameters:

Args:

  • ​lhs (T): 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.

Raises:

If the operation fails.

__rmod__​

__rmod__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse modulo.

Calls the underlying object's __rmod__ method.

Parameters:

Args:

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

Returns:

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

Raises:

If the operation fails.

__rpow__​

__rpow__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse power of.

Parameters:

Args:

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

Returns:

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

Raises:

If the operation fails.

__rlshift__​

__rlshift__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse bitwise left shift.

Parameters:

Args:

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

Returns:

Self: The given value, shifted left by this.

Raises:

If the operation fails.

__rrshift__​

__rrshift__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse bitwise right shift.

Parameters:

Args:

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

Returns:

Self: The given value, shifted right by this.

Raises:

If the operation fails.

__rand__​

__rand__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse bitwise and.

Parameters:

Args:

  • ​lhs (T): 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.

Raises:

If the operation fails.

__ror__​

__ror__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse bitwise OR.

Parameters:

Args:

  • ​lhs (T): 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.

Raises:

If the operation fails.

__rxor__​

__rxor__[T: ConvertibleToPython, //](self, var lhs: T) -> Self

Reverse exclusive OR.

Parameters:

Args:

  • ​lhs (T): 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.

Raises:

If the operation fails.

__iadd__​

__iadd__[T: ConvertibleToPython = PythonObject](mut self, var rhs: T)

Immediate addition and concatenation.

Parameters:

Args:

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

Raises:

If the operation is not supported.

__isub__​

__isub__[T: ConvertibleToPython, //](mut self, var rhs: T)

Immediate subtraction.

Parameters:

Args:

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

Raises:

If the operation is not supported.

__imul__​

__imul__[T: ConvertibleToPython, //](mut self, var rhs: T)

In-place multiplication.

Calls the underlying object's __imul__ method.

Parameters:

Args:

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

Raises:

If the operation is not supported.

__itruediv__​

__itruediv__[T: ConvertibleToPython, //](mut self, var rhs: T)

Immediate division.

Parameters:

Args:

  • ​rhs (T): The value by which this object is divided.

Raises:

If the operation fails.

__ifloordiv__​

__ifloordiv__[T: ConvertibleToPython, //](mut self, var rhs: T)

Immediate floor division.

Parameters:

Args:

  • ​rhs (T): The value by which this object is divided.

Raises:

If the operation fails.

__imod__​

__imod__[T: ConvertibleToPython, //](mut self, var rhs: T)

Immediate modulo.

Parameters:

Args:

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

Raises:

If the operation fails.

__ipow__​

__ipow__[T: ConvertibleToPython, //](mut self, var rhs: T)

Immediate power of.

Parameters:

Args:

  • ​rhs (T): The exponent.

Raises:

If the operation fails.

__ilshift__​

__ilshift__[T: ConvertibleToPython, //](mut self, var rhs: T)

Immediate bitwise left shift.

Parameters:

Args:

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

Raises:

If the operation fails.

__irshift__​

__irshift__[T: ConvertibleToPython, //](mut self, var rhs: T)

Immediate bitwise right shift.

Parameters:

Args:

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

Raises:

If the operation fails.

__iand__​

__iand__[T: ConvertibleToPython, //](mut self, var rhs: T)

Immediate bitwise AND.

Parameters:

Args:

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

Raises:

If the operation fails.

__ixor__​

__ixor__[T: ConvertibleToPython, //](mut self, var rhs: T)

Immediate exclusive OR.

Parameters:

Args:

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

Raises:

If the operation fails.

__ior__​

__ior__[T: ConvertibleToPython, //](mut self, var rhs: T)

Immediate bitwise OR.

Parameters:

Args:

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

Raises:

If the operation fails.

__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.

Raises:

If the attribute does not exist.

__setattr__​

__setattr__[V: ConvertibleToPython, //](self, var name: String, var value: V)

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

Parameters:

Args:

  • ​name (String): The name of the object attribute to set.
  • ​value (V): The new value to be set for that attribute.

Raises:

If setting the attribute fails.

__call__​

__call__[*Ts: ConvertibleToPython & Copyable](self, *args: *Ts.values, *, var **kwargs: Self) -> Self

Call the underlying object as if it were a function.

Parameters:

Args:

  • ​*args (*Ts.values): 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.

Raises:

If the operation fails.

__hash__​

__hash__(self) -> Int

Returns the hash value of the object.

Returns:

Int: The hash value of the object.

Raises:

If the operation fails.

__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.

write_repr_to​

write_repr_to(self, mut writer: T)

Writes the repr of this PythonObject to a writer.

Uses Python's repr() to get the representation of the underlying Python object.

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.

Raises:

If the conversion to Python object fails.

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], MutAnyOrigin]

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.

Raises:

If the operation fails.

downcast_value_ptr​

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

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:

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[mut: Bool, origin: Origin[mut=mut], //, T: ImplicitlyDestructible](ref[origin] self) -> UnsafePointer[T, origin]

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:

  • ​mut (Bool): The mutability of self.
  • ​origin (Origin): The origin of self.
  • ​T (ImplicitlyDestructible): The type of the Mojo value stored in this object.

Returns:

UnsafePointer: A pointer to the inner Mojo value.

Edit this page