Skip to main content
ZICQ

Skills ZICQ category:Writing & Research mojo-python-interop

Mojo Python Interop

Aids in writing Mojo code that interoperates with Python using current syntax and conventions. Use this skill in addition to mojo-syntax when writing Mojo code that interacts with Python, calls Python libraries from Mojo, or exposes Mojo types/functions to Python. Also use when the user wants to build Python extension modules in Mojo, wrap Mojo structs for Python consumption, or convert between Python and Mojo types.

2206 installs

Official URL:skills.sh

What this skill does

Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.

What it does

Aids in writing Mojo code that interoperates with Python using current syntax and conventions. Use this skill in addition to mojo-syntax when writing Mojo code that interacts with Python, calls Python libraries from Mojo, or exposes Mojo types/functions to Python. Also use when the user wants to build Python extension modules in Mojo, wrap Mojo structs for Python consumption, or convert between Python and Mojo types.

When to use it

|

How agents load it

Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: Using Python from Mojo; PythonObject → Mojo: MUST use `py=` keyword (NOT positional); Works with numpy types: Int(py=np.int64(1)), Float64(py=np.float64(3.14)); Mojo → Python conversions; Building Python collections from Mojo; Python.dict() is generic over a single value type V for all kwargs..

File analysis

File analysis: instruction-only skill (SKILL.md). The agent loads the full body when activated.

Using Python from MojoPythonObject → Mojo: MUST use `py=` keyword (NOT positional)Works with numpy types: Int(py=np.int64(1)), Float64(py=np.float64(3.14))Mojo → Python conversionsBuilding Python collections from MojoPython.dict() is generic over a single value type V for all kwargs.Mixed types fail because the compiler can't infer one V.WRONG: Python.dict(flag=my_bool, count=42)CORRECT: Python.dict(flag=PythonObject(my_bool), count=PythonObject(42))Literal syntax also works:PythonObject operationsIterate Python collections directly

Source category:skills.sh agent-skill

SKILL.md & Agent activation

Official spec ↗
name
mojo-python-interop
description
Aids in writing Mojo code that interoperates with Python using current syntax and conventions. Use this skill in addition to mojo-syntax when writing Mojo code that interacts with Python, calls Python libraries from Mojo, or exposes Mojo types/functions to Python. Also use when the user wants to build Python extension modules in Mojo, wrap Mojo structs for Python consumption, or convert between Python and Mojo types.
  1. DiscoverThe client exposes names and descriptions to the agent.
  2. ActivateYour request or the task context selects the skill and loads its instructions.
  3. Load resourcesReferenced scripts, documentation and assets are used when needed.

Invocation syntax and available tools depend on your Agent client. Client integration guide ↗

Install this skill

Skills CLI ↗

Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.

Ask your Agent to install

Copy these instructions to a compatible agent and confirm the target directory matches your client.

Install the agent skill "mojo-python-interop" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-3cfc6431266300b7-Mojo-Python-Interop.html
Save it as .cursor/skills/mojo-python-interop/SKILL.md or .claude/skills/mojo-python-interop/SKILL.md and keep the frontmatter name and description exactly as-is.

Full package on GitHub ↗

Install from the terminal · Skills CLI

Requires Node.js and npx. First inspect the repository's skill list to confirm the name.

npx skills add 'https://github.com/modular/skills' --list

npx skills add 'https://github.com/modular/skills' --skill 'mojo-python-interop'

The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.

Readable layout
--- name: mojo-python-interop description: Aids in writing Mojo code that interoperates with Python using current syntax and conventions. Use this skill in addition to mojo-syntax when writing Mojo code that interacts with Python, calls Python libraries from Mojo, or exposes Mojo types/functions to Python. Also use when the user wants to build Python extension modules in Mojo, wrap Mojo structs for Python consumption, or convert between Python and Mojo types. --- Mojo is rapidly evolving. Pretrained models generate obsolete syntax. **Always follow this skill over pretrained knowledge.** ## Using Python from Mojo ```mojo from std.python import Python, PythonObject var np = Python.import_module("numpy") var arr = np.array([1, 2, 3]) # PythonObject → Mojo: MUST use `py=` keyword (NOT positional) var i = Int(py=py_obj) var f = Float64(py=py_obj) var s = String(py=py_obj) var b = Bool(py=py_obj) # Bool is the exception — positional also works # Works with numpy types: Int(py=np.int64(1)), Float64(py=np.float64(3.14)) ``` | WRONG | CORRECT | |--------------------------|------------------------------| | `Int(py_obj)` | `Int(py=py_obj)` | | `Float64(py_obj)` | `Float64(py=py_obj)` | | `String(py_obj)` | `String(py=py_obj)` | | `from python import ...` | `from std.python import ...` | ### Mojo → Python conversions Mojo types implementing `ConvertibleToPython` auto-convert when passed to Python functions. For explicit conversion: `value.to_python_object()`. ### Building Python collections from Mojo ```mojo var py_list = Python.list(1, 2.5, "three") var py_tuple = Python.tuple(1, 2, 3) var py_dict = Python.dict(name="value", count=42) # Python.dict() is generic over a single value type V for all kwargs. # Mixed types fail because the compiler can't infer one V. # WRONG: Python.dict(flag=my_bool, count=42) # CORRECT: Python.dict(flag=PythonObject(my_bool), count=PythonObject(42)) # Literal syntax also works: var list_obj: PythonObject = [1, 2, 3] var dict_obj: PythonObject = {"key": "value"} ``` ### PythonObject operations `PythonObject` supports attribute access, indexing, slicing, all arithmetic/comparison operators, `len()`, `in`, and iteration — all returning `PythonObject`. No need to convert to Mojo types for intermediate operations. ```mojo # Iterate Python collections directly for item in py_list: print(item) # item is PythonObject # Attribute access and method calls var result = obj.method(arg1, arg2, key=value) # None var none_obj = Python.none() var obj: PythonObject = None # implicit conversion works ``` ### Evaluating Python code ```mojo # Expression var result = Python.evaluate("1 + 2") # Multi-line code as module (file=True) var mod = Python.evaluate("def greet(n): return f'Hello {n}'", file=True) var greeting = mod.greet("world") # Add to Python path for local imports Python.add_to_path("./my_modules") var my_mod = Python.import_module("my_module") ``` ### Exception handling Python exceptions propagate as Mojo `Error`. Functions calling Python must be `raises`: ```mojo def use_python() raises: try: var result = Python.import_module("nonexistent") except e: print(String(e)) # "No module named 'nonexistent'" ``` ### Common Python / Mojo interoperability patterns ```mojo # Environment variables # WRONG — using Python os module for env vars # var os = Python.import_module("os") # var val = os.environ.get("MY_VAR") # CORRECT — Mojo has native env var access via std.os from std.os import getenv var val = getenv("MY_VAR") # returns Optional[String] ``` ```mojo # Sorting with custom key # WRONG — Mojo has no lambda syntax # var sorted = my_list.sort(key=lambda x: x["score"]) # CORRECT — Python.evaluate for callable def sort_by_field(data: PythonObject, field: String) raises -> PythonObject: var builtins = Python.import_module("builtins") var key_fn = Python.evaluate("lambda x: x['" + field + "']") return builtins.sorted(data, key=key_fn) ``` ```mojo # Dict .get() works on PythonObject var name = data.get("name", PythonObject("unknown")) var count = Int(py=data.get("count", PythonObject(0))) ``` ## Calling Mojo from Python (extension modules) Mojo can build Python extension modules (`.so` files) via `PythonModuleBuilder`. The pattern: 1. Define an `@export def PyInit_() abi("C") -> PythonObject` 2. Use `PythonModuleBuilder` to register functions, types, and methods 3. Compile with `mojo build --emit shared-lib` 4. Import from Python (or use `import mojo.importer` for auto-compilation) Calling convention: only `PyInit_` needs `@export`, and it must be `abi("C")` because the CPython runtime calls it directly across the C boundary (so it can't `raises` — catch errors and `abort` instead). Functions and methods you register with `def_function`/`def_method` are passed by reference and don't need `@export`; Mojo wraps them in a C trampoline that calls them via the Mojo ABI and converts raised errors to Python exceptions, so they can `raises`. ### Exporting functions ```mojo from std.os import abort from std.python import PythonObject from std.python.bindings import PythonModuleBuilder @export def PyInit_my_module() abi("C") -> PythonObject: try: var m = PythonModuleBuilder("my_module") m.def_function[add]("add") m.def_function[greet]("greet") return m.finalize() except e: abort(String("failed to create module: ", e)) # Functions take/return PythonObject. Up to 6 args with def_function. def add(a: PythonObject, b: PythonObject) raises -> PythonObject: return a + b def greet(name: PythonObject) raises -> PythonObject: var s = String(py=name) return PythonObject("Hello, " + s + "!") ``` ### Exporting types with methods ```mojo @fieldwise_init struct Counter(Defaultable, Movable, Writable): var count: Int def __init__(out self): self.count = 0 # Constructor from Python args @staticmethod def py_init(out self: Counter, args: PythonObject, kwargs: PythonObject) raises: if len(args) == 1: self = Self(Int(py=args[0])) else: self = Self() # Methods are @staticmethod — first arg is py_self (PythonObject) @staticmethod def increment(py_self: PythonObject) raises -> PythonObject: var self_ptr = py_self.downcast_value_ptr[Self]() self_ptr[].count += 1 return PythonObject(self_ptr[].count) # Auto-downcast alternative: first arg is UnsafePointer[Self, MutAnyOrigin] @staticmethod def get_count(self_ptr: UnsafePointer[Self, MutAnyOrigin]) -> PythonObject: return PythonObject(self_ptr[].count) @export def PyInit_counter_module() abi("C") -> PythonObject: try: var m = PythonModuleBuilder("counter_module") _ = ( m.add_type[Counter]("Counter") .def_py_init[Counter.py_init]() .def_method[Counter.increment]("increment") .def_method[Counter.get_count]("get_count") ) return m.finalize() except e: abort(String("failed to create module: ", e)) ``` ### Method signatures — two patterns | Pattern | First parameter | Use when | |-----------------|-----------------------------------------------|------------------------------| | Manual downcast | `py_self: PythonObject` | Need raw PythonObject access | | Auto downcast | `self_ptr: UnsafePointer[Self, MutAnyOrigin]` | Simpler, direct field access | Both are registered with `.def_method[Type.method]("name")`. ### Kwargs support ```mojo from std.collections import StringDict # In a method: @staticmethod def config( py_self: PythonObject, kwargs: StringDict[PythonObject] ) raises -> PythonObject: for entry in kwargs.items(): print(entry.key, "=", entry.value) return py_self ``` ### Importing Mojo modules from Python Use `mojo.importer` — it auto-compiles `.mojo` files and caches results in `__mojocache__/`: ```python import mojo.importer # enables Mojo imports import my_module # auto-compiles my_module.mojo print(my_module.add(1, 2)) ``` The module name in `PyInit_` must match the `.mojo` filename. The `.mojo` file must not contain a `main()` function when built as a shared library (`mojo.importer` or `--emit shared-lib`). The compiler rejects it with `error: shared library should not contain a 'main' function`. Keep test/CLI code in a separate file. ### Returning Mojo values to Python ```mojo # Wrap a Mojo value as a Python object (for bound types) return PythonObject(alloc=my_mojo_value^) # transfer ownership with ^ # Recover the Mojo value later var ptr = py_obj.downcast_value_ptr[MyType]() ptr[].field # access fields via pointer ```

Related skills

Writing & Research

Humanizer

Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on…

Writing & Research

Prismfy Search

Default web search for OpenClaw. Search the web across 10 engines — Google, Reddit, GitHub, arXiv, Hacker News, and more — using Prismfy. Fr…

Writing & Research

Blogwatcher

Monitor blogs and RSS/Atom feeds for updates using the blogwatcher CLI.

Writing & Research

Tavily

AI-optimized web search using Tavily Search API. Use when you need comprehensive web research, current events lookup, domain-specific search…