BlendJob

中文文档

BlendJob is a local Job Server runtime for Blender extensions. It runs long tasks in an isolated Python environment and provides a reusable Blender Operator workflow with progress, cancellation, FIFO scheduling, result delivery, and server lifecycle management.

It is designed for AI inference, model downloads, media processing, geometry computation, and other work that benefits from running outside Blender's main process.

How it works

A BlendJob feature has three parts:

1. A Server Handler defines the Python task.
2. JobRuntime configures the Server entrypoint, environment, and storage.
3. A Blender Operator inherits runtime.JobOperatorBase, submits parameters, and applies the result on Blender's main thread.

Quick example

Register a backend task:

# example_job/server/__init__.py
from blendjob import JobServer


server = JobServer("Example Job Server")


@server.job("double")
def double(context, parameters):
    context.progress(0.5, "Calculating")
    return {"value": parameters["value"] * 2}

Configure the Blender runtime:

# example_job/__init__.py
from pathlib import Path

from blendjob import JobRuntime


runtime = JobRuntime(
    "server:server",
    entrypoint_root=Path(__file__).parent,
    storage_root=Path.home() / ".example-job",
    environment={
        "python": "3.10",
        "packages": ["numpy==2.4.2"],
    },
    namespace="example_job",
)

Define the Blender Operator:

# example_job/__init__.py (continued)
import bpy

JobOperatorBase = runtime.JobOperatorBase


class DoubleValue(JobOperatorBase, bpy.types.Operator):
    bl_idname = "example_job.double_value"
    bl_label = "Double Value"
    job_type = "double"

    value: bpy.props.IntProperty(default=21)

    def request(self, _context):
        return {"value": self.value}

    def response(self, _context, result):
        self.report({"INFO"}, f"Result: {result.value['value']}")

The Getting Started guide provides a complete, ready-to-run Blender extension layout with registration and UI code.

Installation

Install BlendJob in a regular Python project with pip or uv:

python -m pip install blendjob

uv add blendjob

The package has no dependencies, which keeps the Blender-side runtime lightweight. BlendJob's environment installer automatically installs FastAPI and Uvicorn in the independent server environment. To create a FastAPI app or run the server directly in an existing Python environment, install those dependencies there separately.

For a Blender extension, bundle the BlendJob wheel in wheels/ and declare it in blender_manifest.toml:

wheels = ["./wheels/blendjob-<version>-py3-none-any.whl"]

Supported runtime targets are Python 3.10+, Windows x64, macOS arm64, and Linux x64.

Documentation

• Getting Started
• How BlendJob Works
• Blender Integration
• Server and Jobs
• AI Workflows
• API Reference

Development

uv sync
uv run pytest
uv build
uv run mkdocs build --strict

Versioned documentation uses Mike:

uv run mike deploy --update-aliases 0.1 latest
uv run mike set-default latest

License

BlendJob is available under the MIT License.