fix(python-runner): compute full module path so relative imports work

[riturajFi]

Closes #746

Problem

The Python step runner was incorrectly setting module.__package__ to only the last directory name (e.g. "endpoints").
As a result, relative imports like:

from ..repositories import db_repo

failed with:

ImportError: attempted relative import beyond top-level package

This prevented Motia from correctly loading step files with nested package structures.

---

Solution

• Updated the runner logic in get-config.py to compute the full dotted module path relative to the steps/ directory.

  • Example:

    • File: steps/endpoints/python_api_step.py
    • Old package: "endpoints"
    • New package: "steps.endpoints"
    • Full module name: "steps.endpoints.python_api_step"

• Set module.__package__ and sys.modules[...] to this full dotted name before executing the module.

• This ensures Python has the correct package context, so relative imports always resolve properly.

Screencast.from.2025-10-01.09-54-08.webm

---

Benefits

• Relative imports (..repositories, ..utils, etc.) now work across all nested step files.
• No need to rewrite individual step files.
• Future-proof: supports arbitrary nesting depth under the steps/ directory.
• Compatible with namespace packages (no __init__.py required).

---

Example

Before (broken):

module.__package__ = "endpoints"
ImportError: attempted relative import beyond top-level package

After (fixed):

module.__package__ = "steps.endpoints"
Relative import '..repositories' resolves correctly

---

[vercel]

@riturajFi is attempting to deploy a commit to the motia Team on Vercel.

A member of the Team first needs to authorize it.

[rohitg00]

Thanks @riturajFi, let me check with the team to review this quickly, thanks!

[sergiofilhowz]

I'm trying to test it and doesn't seem to work, am I doing anything wrong?

api2_step.py

from pydantic import BaseModel
from typing import Optional
from ..python.repo import Repo

class PetRequest(BaseModel):
    name: str
    photo_url: str

class FoodOrder(BaseModel):
    id: str
    quantity: int

class RequestBody(BaseModel):
    pet: PetRequest
    food_order: Optional[FoodOrder] = None

config = {
    "type": "api",
    "name": "PythonApiTrigger2",
    "description": "basic-tutorial api trigger",
    "flows": ["python-tutorial"],
    "method": "POST",
    "path": "/python-basic-tutorial2",
    "bodySchema": RequestBody.model_json_schema(),
    "emits": [],
}

async def handler(req, context):
    body = req.get("body", {})
    context.logger.info("Step 01 – Processing API Step", {"body": body})

    repo = Repo()
    context.logger.info("Repo", {"repo": repo.say_hello()})

    return {"status": 200, "body": {"traceId": context.trace_id}}

[riturajFi]

Checking this asap

[riturajFi]

Hi @sergiofilhowz,

Here’s the detailed process to reproduce the bug and verify the fix:

---

🧪 Steps to Reproduce (on main branch)

1. Build the project.

2. Create the following folder structure:

   /steps
     ├── __init__.py
     ├── /endpoints
     │    ├── __init__.py
     │    └── python_api_step.py
     └── /repositories
          ├── __init__.py
          └── db_repo.py
   

3. Add the following contents:

python_api_step.py

from ..repositories.db_repo import get_data

config = {
    "type": "api",
    "name": "nestedpython",
    "path": "/api",
    "method": "GET",
    "emits": []
}

async def handler(req, ctx):
    return {
        "status": 200,
        "body": get_data()
    }

db_repo.py

def get_data():
    return 1

4. Run the project.
   You’ll see this error:

   Error running Python module: attempted relative import beyond top-level package
   

---

✅ Verification (on feature branch)

After switching to this feature branch and repeating the same steps, the project runs successfully:
You can also hit the api and check the successfull implementation of relative imports in python steps -

➜ [INFO] Activating Python environment 
➜ [INFO] Using Python <projectDir>/python_modules/bin/python
➜ [INFO] Site-packages path <projectDir>/python_modules/lib/python3.13/site-packages
➜ [REGISTERED] Step (API) steps/endpoints/python_api_step.py registered
[motia-plugins] ✓ Validated 3 plugin(s) successfully
[motia-plugins] Initialized with 3 plugin(s)
[motia-plugins] Dev server configured, HMR enabled
[motia-plugins] Build started
🚀 Server ready and listening on port 3000
🔗 Open http://localhost:3000 to open workbench 🛠️

[sergiofilhowz]

Thanks for providing this information, however, the issue happens on my project, we need to ensure it doesn't happen.

[github-actions]

⚠️ This PR is quite large (>1000 lines). Consider splitting it into smaller PRs for easier review.

[ytallo]

Is this file necessary?

[riturajFi]

Sorry i placed these by mistake

[ytallo]

Is this file necessary?

[guibeira]

Do we need to include it at position 0? This will require a bit shift of all elements. If it's not necessary, can we use append?