API Reference

This section provides detailed information about the ispawn Python API.

Config

class ispawn.domain.config.BaseMode(value)

Bases: str, Enum

Base class for mode enums with common string conversion functionality.

classmethod from_str(value: str) → BaseMode

Create mode from string.

class ispawn.domain.config.CertMode(value)

Bases: BaseMode

Available certificate modes for remote proxy.

LETSENCRYPT = 'letsencrypt'

PROVIDED = 'provided'

class ispawn.domain.config.Config(install_mode: str, mode: str, domain: str, subnet: str, name: str, dns: List[str] = None, user_in_namespace: bool = False, cert_mode: str | None = None, cert_dir: str | None = None, email: str | None = None, volumes: str = None, mount_point: str = None, env_chunk_path: str | None = None, dockerfile_chunk_path: str | None = None, entrypoint_chunk_path: str | None = None, home_prefix: str = '/home/', timezone: str = 'Europe/Paris')

Bases: object

Configuration for reverse proxy and SSL certificates.

Attrs:

install_mode: Installation mode system or user mode: Proxy mode (local or remote) domain: Domain name for services subnet: Docker network subnet name: Base name network_name: Network name cert_mode: Certificate mode (required for remote proxy) cert_dir: Directory for SSL certificates email: Email for Let’s Encrypt (required if cert_mode is letsencrypt) env_chunk_path: Path to environment file for Docker builds dockerfile_chunk_path: Path to dockerfile chunk for Docker builds entrypoint_chunk_path: Path to entrypoint chunk for Docker builds

property base_log_dir: str

Get base log directory path.

property config_dir: str

Get config dir

property config_path: str

Get config path

property container_name_prefix: str

Get container name prefix

property domain_prefix: str

Get domain prefix

classmethod from_yaml(fh: TextIO) → Config

Create Config from YAML.

static get_system_dir() → str

Get system-wide installation directory.

Returns:

Path to system-wide installation directory (/etc/ispawn)

property image_name_prefix: str

Get image name prefix

property is_local: bool

Check if using local proxy mode.

property is_system_install: bool

Check if using system-wide installation.

classmethod load(user_mode=False) → Config

Create Config from system configuration using from_yaml.

property network_name: str

Get Docker network name.

property requires_email: bool

Check if email is required for certificate configuration.

save() → None

Save proxy configuration to system or user configuration.

to_yaml(fh: TextIO) → None

Serialize proxy configuration to YAML.

property user_root_dir: str

Get user root directory path.

class ispawn.domain.config.InstallMode(value)

Bases: BaseMode

Available installation modes.

SYSTEM = 'system'

USER = 'user'

class ispawn.domain.config.ProxyMode(value)

Bases: BaseMode

Available reverse proxy modes.

LOCAL = 'local'

REMOTE = 'remote'

Image

class ispawn.domain.image.ImageConfig(config: Config, base: str, services: List[str])

Bases: object

Configuration for building a Docker image with comprehensive settings.

Attributes:

base (str): Base Docker image to build from services (List[str]): List of services to include in the image config (Config): Configuration object containing build settings

property dockerfile_template_path: Path

Get path to the Dockerfile template.

Returns:

Path: Path to Dockerfile template

property entrypoint_template_path: Path

Get path to the entrypoint script template.

Returns:

Path: Path to entrypoint script template

get_build_context() → Dict[str, Any]

Get the complete build context for the image.

Returns:

Dict[str, Any]: Complete build context including all necessary

files and arguments

get_dockerfile_args() → Dict[str, str]

Get Dockerfile template context.

get_entrypoint_args() → Dict[str, str]

Get entrypoint template context.

get_template_context(template_type: str) → Dict[str, Any]

Get template context for specified template type.

Args:

template_type: Type of template (‘Dockerfile’ or ‘entrypoint.sh’)

Returns:

Dict[str, Any]: Template context variables

property target_image: str

Get the target image name.

Returns:

str: Target image name with prefix and tag

class ispawn.domain.image.Service(value)

Bases: Enum

JUPYTER = 'jupyter'

JUPYTERHUB = 'jupyterhub'

JUPYTERLAB = 'jupyterlab'

RSTUDIO = 'rstudio'

VSCODE = 'vscode'

classmethod from_str(s: str) → Service

property port: int | None

Get the port number defined in the service’s config.

property volumes: Dict[str, str]

Get the volume mappings defined in the service’s config.

Returns:

Dict[str, str]: Dictionary mapping host directory names to container

paths

ispawn.domain.image.from_str()

ispawn.domain.image.port(self) → int | None

Get the port number defined in the service’s config.

ispawn.domain.image.volumes(self) → Dict[str, str]

Get the volume mappings defined in the service’s config.

Returns:

Dict[str, str]: Dictionary mapping host directory names to container

paths

Container

class ispawn.domain.container.ContainerConfig(name: str, config: Config, image_config: ImageConfig, volumes: List[List[str]], group: str | None = None, user: str | None = None, sudo: bool = True)

Bases: object

Configuration for a container with comprehensive settings.

Attributes:

name (str): Original container name group (str): Required group for RStudio access (defaults to username)

environment() → Dict[str, str]

Generate environment variables for the container.

get_labels() → Dict[str, str]

Generate container labels for Traefik routing and service

identification.

Returns:

Dict[str, str]: Dictionary of Docker labels

get_service_domain(service: Service) → str

Generate service domain name.

Args:

service: Service type

Returns:

str: Service domain name

Services

Image Service

class ispawn.services.image.ImageService(config: Config)

Bases: object

Service for handling Docker image operations.

build_image(config: ImageConfig) → Image

Build a Docker image using the provided configuration.

Args:

config: ImageConfig instance with build configuration

Returns:

Built Docker image

Raises:

ImageError: If image build fails

check_image(config: ImageConfig) → bool

Check if a Docker image exists based on the provided configuration.

list_images() → List[Dict[str, str]]

List all ispawn images.

Args:

prefix: Image name prefix to filter by

Returns:

List of image information dictionaries

Raises:

ImageError: If listing images fails

remove_image(digest: str, force: bool = False) → None

Remove a Docker image.

Args:

name: Name of the image to remove force: Force removal of the image

Raises:

ImageError: If image removal fails

Container Service

class ispawn.services.container.ContainerService(config: Config)

Bases: object

Service for handling Docker operations.

get_container_info(container_id: str) → Dict[str, str]

list_containers(running: bool = None) → List[Dict[str, str]]

List all ispawn containers.

Args:

running (bool, optional):

If True, only running containers are returned. If False, only stopped containers are returned. Defaults to None (all containers).

Returns:

List[Dict[str, str]]: List of container information

Raises:

ContainerError: If container listing fails

remove_container(container_id: str, force: bool = False) → None

run_container(config: ContainerConfig, force: bool = False) → Container

Run a Docker container with the specified configuration.

Args:

container: Container configuration force: Whether to force replace an existing container

Returns:

Running Docker container

Raises:

ContainerError: If container operations fail

start_container(container_id: str) → None

stop_container(container_id: str) → None

Config Manager

Configuration manager for ispawn.

class ispawn.services.config.ConfigManager(config: Config, force: bool = False)

Bases: object

Configuration manager for ispawn.

apply_config() → None

Apply the configuration.

Creates necessary directories, generates certificates, sets up Docker network, and configures traefik.

Raises:

ConfigurationError: If configuration cannot be applied

remove_config() → None

Remove the configuration and cleanup resources.