Template Builder

Version: 0.3.0
Last Verified: 2025-01-27
Package: hopx-ai on PyPI

Overview

The Template class provides a fluent API for building custom sandbox templates. Use this to create reusable templates with specific configurations, dependencies, and ready checks. Templates are built from base images and can include file copies, command execution, environment variables, port exposure, and ready checks.

Import

from hopx_ai.template import Template

Base Image Methods

`from_ubuntu_image`

Start from Ubuntu base image.

Template.from_ubuntu_image(version) -> Template

Parameters:

version (str): Ubuntu version (e.g., "22.04")

Returns: Template - Template instance (fluent API) Expected Output:

Template instance ready for configuration

`from_python_image`

Start from Python base image.

Template.from_python_image(version) -> Template

Parameters:

version (str): Python version (e.g., "3.11")

Expected Output:

Template instance ready for configuration

`from_node_image`

Start from Node.js base image.

Template.from_node_image(version) -> Template

Parameters:

version (str): Node.js version (e.g., "20")

Expected Output:

Template instance ready for configuration

`from_image`

Start from any Docker image.

Template.from_image(image, auth=None) -> Template

Parameters:

image (str): Docker image name
auth (Dict, optional): Authentication credentials

Expected Output:

Template instance ready for configuration

Configuration Methods

`copy`

Copy files to the template.

Template.copy(src, dest, options=None) -> Template

Parameters:

src (str): Source path
dest (str): Destination path
options (Dict, optional): Copy options

Expected Output:

Template instance (fluent API)

`run`

Run command in template.

Template.run(command) -> Template

Parameters:

command (str): Command to execute

Expected Output:

Template instance (fluent API)

Example:

Template.from_python_image("3.11").run("pip install requests")

`env`

Set environment variable.

Template.env(key, value) -> Template

Parameters:

key (str): Environment variable name
value (str): Environment variable value

Expected Output:

Template instance (fluent API)

`expose`

Expose port.

Template.expose(port) -> Template

Parameters:

port (int): Port number to expose

Expected Output:

Template instance (fluent API)

`workdir`

Set working directory.

Template.workdir(path) -> Template

Parameters:

path (str): Working directory path

Expected Output:

Template instance (fluent API)

`ready_check`

Set ready check.

Template.ready_check(check) -> Template

Parameters:

check (ReadyCheck): Ready check object

Expected Output:

Template instance (fluent API)

See Ready Checks for available ready checks.

`start_cmd`

Set start command.

Template.start_cmd(command) -> Template

Parameters:

command (str): Start command

Expected Output:

Template instance (fluent API)

Building

`build`

Build the template.

await Template.build(options=None) -> BuildResult

Parameters:

options (Dict, optional): Build options

Returns: BuildResult - Build result with template ID and status Example:

import asyncio

async def build_template():
    template = (
        Template
        .from_python_image("3.11")
        .run("pip install flask")
        .expose(5000)
        .start_cmd("python app.py")
    )
    
    result = await template.build()
    print(f"Template ID: {result.template_id}")

asyncio.run(build_template())

Expected Output:

Template ID: template_abc123xyz

Examples

Example 1: Simple Python Template

from hopx_ai.template import Template
import asyncio

async def main():
    template = (
        Template
        .from_python_image("3.11")
        .run("pip install requests pandas")
        .env("PYTHONUNBUFFERED", "1")
    )
    
    result = await template.build()
    print(f"Built template: {result.template_id}")

asyncio.run(main())

Expected Output:

Built template: template_abc123xyz

Example 2: Web Server Template

from hopx_ai.template import Template, wait_for_port
import asyncio

async def main():
    template = (
        Template
        .from_node_image("20")
        .run("npm install express")
        .copy("./app.js", "/app/app.js")
        .expose(3000)
        .start_cmd("node /app/app.js")
        .ready_check(wait_for_port(3000))
    )
    
    result = await template.build()
    print(f"Web server template: {result.template_id}")

asyncio.run(main())

Expected Output:

Web server template: template_abc123xyz

Ready Checks - Ready check utilities
Sandbox - Use templates with Sandbox.create(template=...)

Next Steps

Now that you understand template building, explore:

Ready Checks - Add readiness verification
Building Templates - Learn template building concepts
Template Configuration - Configure templates
CLI Reference - Use HopX from the command line
Custom Templates - Build custom templates

Python SDK

JavaScript SDK

Overview

Import

Base Image Methods

`from_ubuntu_image`

`from_python_image`

`from_node_image`

`from_image`

Configuration Methods

`copy`

`run`

`env`

`expose`

`workdir`

`ready_check`

`start_cmd`

Building

`build`

Examples

Example 1: Simple Python Template

Example 2: Web Server Template

See Also

Next Steps

​Overview

​Import

​Base Image Methods

​from_ubuntu_image

​from_python_image

​from_node_image

​from_image

​Configuration Methods

​copy

​run

​env

​expose

​workdir

​ready_check

​start_cmd

​Building

​build

​Examples

​Example 1: Simple Python Template

​Example 2: Web Server Template

​Related Classes

​See Also

​Next Steps

Overview

Import

Base Image Methods

`from_ubuntu_image`

`from_python_image`

`from_node_image`

`from_image`

Configuration Methods

`copy`

`run`

`env`

`expose`

`workdir`

`ready_check`

`start_cmd`

Building

`build`

Examples

Example 1: Simple Python Template

Example 2: Web Server Template

Related Classes

See Also

Next Steps