Skip to main content

​
Overview

The JobClient class provides methods for submitting jobs to SyftBox, managing job status, and querying jobs across datasites.

​
Factory Function

​
get_client()

Create a JobClient from a SyftBox folder. 
from syft_job import get_client

client = get_client(
    syftbox_folder_path="/path/to/syftbox",
    email="[email protected]",
    user_email="[email protected]"  # Optional
)
​
syftbox_folder_path
str
required
Path to the SyftBox folder
​
email
str
required
Root user email address
​
user_email
str
Optional target user email for job views (defaults to root email)
​
return
JobClient
Configured JobClient instance

​
JobClient Class

​
Constructor

from syft_job import JobClient, SyftJobConfig

config = SyftJobConfig.from_syftbox_folder(
    syftbox_folder_path="/path/to/syftbox",
    email="[email protected]"
)

client = JobClient(config, target_datasite_owner_email="[email protected]")
​
config
SyftJobConfig
required
Configuration object for the job system
​
target_datasite_owner_email
str
Email of the datasite owner whose jobs to manage (defaults to config.email)

​
Methods

​
submit_python_job()

Submit a Python job to a user’s datasite. 
job_path = client.submit_python_job(
    user="[email protected]",
    code_path="./my_script.py",
    job_name="Data Analysis",
    dependencies=["numpy", "pandas==1.5.0"],
    entrypoint="main.py"  # For folder submissions
)
​
user
str
required
Email address of the user to submit job for
​
code_path
str
required
Path to Python file or folder containing Python code
​
job_name
str
Name of the job (defaults to “Job - ”)
​
dependencies
List[str]
List of Python packages to install (e.g., [“numpy”, “pandas==1.5.0”])
​
entrypoint
str
Entry point file name for folder submissions (auto-detected if not provided)
​
return
Path
Path to the created job directory
Auto-detection rules:
  • For folders: Looks for main.py first, then single .py file at root
  • For files: Uses the file name as entrypoint
Example with folder: 
# Submitting a project folder
job_path = client.submit_python_job(
    user="[email protected]",
    code_path="./my_project",
    job_name="ML Training",
    dependencies=["scikit-learn", "numpy"],
    entrypoint="main.py"
)

​
submit_bash_job()

Submit a bash script job to a user’s datasite. 
script = """#!/bin/bash
echo "Processing data..."
python analyze.py
"""

job_path = client.submit_bash_job(
    user="[email protected]",
    script=script,
    job_name="Batch Processing"
)
​
user
str
required
Email address of the user to submit job for
​
script
str
required
Bash script content to execute
​
job_name
str
Name of the job (defaults to “Job - ”)
​
return
Path
Path to the created job directory

​
setup_ds_job_folder_as_do()

Create a data scientist-specific job subdirectory with write permissions. 
ds_folder = client.setup_ds_job_folder_as_do(ds_email="[email protected]")
​
ds_email
str
required
Email of the data scientist to create the folder for
​
return
Path
Path to the created DS job folder

​
get_job_status()

Get the status of a job based on marker files. 
status = client.get_job_status(job_path)
# Returns: "inbox", "approved", or "done"
​
job_path
Path
required
Path to the job directory
​
return
str
Job status: “inbox”, “approved”, or “done”

​
Status Check Methods

# Check if job is approved
is_approved = client.is_job_approved(job_path)

# Check if job is done
is_done = client.is_job_done(job_path)

# Check if job is in inbox
is_inbox = client.is_job_inbox(job_path)
​
job_path
Path
required
Path to the job directory
​
return
bool
True if job is in the specified status

​
Properties

​
jobs

Get all jobs from all peer directories as an indexable list. 
# Get all jobs
all_jobs = client.jobs

# Access by index
first_job = client.jobs[0]

# Access by name
my_job = client.jobs["Data Analysis"]

# Iterate over jobs
for job in client.jobs:
    print(f"{job.name}: {job.status}")

# Display in Jupyter
print(client.jobs)  # Shows formatted tables
​
return
JobsList
JobsList containing all jobs grouped by user, sorted by submission time

​
Configuration

​
SyftJobConfig

Configuration object for the job system. 
from syft_job import SyftJobConfig

config = SyftJobConfig.from_syftbox_folder(
    syftbox_folder_path="/path/to/syftbox",
    email="[email protected]"
)
​
syftbox_folder_path
str
required
Path to the SyftBox folder
​
email
str
required
User email address
Configuration Fields:
​
syftbox_folder
Path
Path to SyftBox root folder
​
email
str
User email address
Helper Methods: 
# Get user directory
user_dir = config.get_user_dir("[email protected]")
# Returns: Path("syftbox/[email protected]")

# Get job directory
job_dir = config.get_job_dir("[email protected]")
# Returns: Path("syftbox/[email protected]/app_data/job")

​
Complete Example

from syft_job import get_client

# Initialize client
client = get_client(
    syftbox_folder_path="~/.syftbox",
    email="[email protected]"
)

# Submit a Python job
job_path = client.submit_python_job(
    user="[email protected]",
    code_path="./analysis.py",
    job_name="Monthly Report",
    dependencies=["pandas", "matplotlib"]
)

print(f"Job submitted to: {job_path}")

# Check all jobs
for job in client.jobs:
    if job.status == "inbox":
        print(f"New job: {job.name} from {job.submitted_by}")

Build docs developers (and LLMs) love

Get started for freeTalk to us