Client¶

class dapi.client.DSClient(tapis_client=None, **auth_kwargs)[source]¶

Bases: object

Main client for interacting with DesignSafe resources via Tapis V3 using dapi.

The DSClient provides a high-level interface for working with DesignSafe resources through the Tapis V3 API. It handles authentication and provides organized access to different service areas including applications, files, jobs, systems, and databases.

Parameters:

tapis_client (Tapis, optional) – Pre-authenticated Tapis client instance. If provided, it will be used instead of creating a new one.
**auth_kwargs – Additional authentication arguments passed to auth.init() when tapis_client is not provided. See auth.init() for available options.

tapis¶

The underlying authenticated Tapis client instance.

Type:: Tapis

apps¶

Interface for application discovery and details.

Type:: AppMethods

files¶

Interface for file operations (upload, download, list).

Type:: FileMethods

jobs¶

Interface for job submission and monitoring.

Type:: JobMethods

systems¶

Interface for system information and queues.

Type:: SystemMethods

db¶

Interface for database connections and queries.

Type:: DatabaseAccessor

Raises:

TypeError – If tapis_client is provided but is not a Tapis instance.
AuthenticationError – If authentication fails when creating a new Tapis client.

Parameters:

tapis_client (Tapis | None)

Example

Basic usage with automatic authentication:

>>> ds = DSClient()
Enter DesignSafe Username: myuser
Enter DesignSafe Password: [hidden]
Authentication successful.

Using explicit credentials:

>>> ds = DSClient(username="myuser", password="mypass")
Authentication successful.

Using a pre-authenticated Tapis client:

>>> tapis = Tapis(base_url="https://designsafe.tapis.io", ...)
>>> tapis.get_tokens()
>>> ds = DSClient(tapis_client=tapis)

__init__(tapis_client=None, **auth_kwargs)[source]¶

Initialize the DSClient with authentication and service interfaces.

Parameters:

tapis_client (Tapis, optional) – Pre-authenticated Tapis client instance. If provided, it will be used instead of creating a new one.
**auth_kwargs – Additional authentication arguments passed to auth.init() when tapis_client is not provided. Common arguments include: - username (str): DesignSafe username - password (str): DesignSafe password - base_url (str): Tapis base URL - env_file (str): Path to .env file with credentials

Raises:

TypeError – If tapis_client is provided but is not a Tapis instance.
AuthenticationError – If authentication fails when creating new client.

class dapi.client.AppMethods(tapis_client)[source]¶

Bases: object

Interface for Tapis application discovery and details retrieval.

This class provides methods for finding and getting detailed information about Tapis applications available for job submission.

Parameters:: tapis_client (Tapis) – Authenticated Tapis client instance.

__init__(tapis_client)[source]¶

Initialize AppMethods with a Tapis client.

Parameters:: tapis_client (Tapis) – Authenticated Tapis client instance.

find(*args, **kwargs)[source]¶

Search for Tapis apps matching a search term.

This is a convenience wrapper around apps_module.find_apps().

Parameters:

*args – Positional arguments passed to find_apps().
**kwargs – Keyword arguments passed to find_apps().

Returns:

List of matching Tapis app objects.

Return type:

List[Tapis]

Raises:

AppDiscoveryError – If the search fails or encounters an error.

get_details(*args, **kwargs)[source]¶

Get detailed information for a specific app ID and version.

This is a convenience wrapper around apps_module.get_app_details().

Parameters:

*args – Positional arguments passed to get_app_details().
**kwargs – Keyword arguments passed to get_app_details().

Returns:

Tapis app object with full details, or None if not found.

Return type:

Optional[Tapis]

Raises:

AppDiscoveryError – If the retrieval fails or encounters an error.

class dapi.client.FileMethods(tapis_client)[source]¶

Bases: object

Interface for file operations on Tapis storage systems.

This class provides methods for uploading, downloading, listing files, and translating DesignSafe-style paths to Tapis URIs.

Parameters:: tapis_client (Tapis) – Authenticated Tapis client instance.

__init__(tapis_client)[source]¶

Initialize FileMethods with a Tapis client.

Parameters:: tapis_client (Tapis) – Authenticated Tapis client instance.

to_uri(*args, **kwargs)[source]¶

Translate DesignSafe-style paths to Tapis URIs.

Parameters:

*args – Positional arguments passed to get_ds_path_uri().
**kwargs – Keyword arguments passed to get_ds_path_uri().

Returns:

The corresponding Tapis URI (e.g., tapis://system-id/path).

Return type:

str

Raises:

FileOperationError – If path translation fails.
ValueError – If the input path format is unrecognized.

to_path(*args, **kwargs)[source]¶

Translate Tapis URIs to DesignSafe local paths.

Parameters:

*args – Positional arguments passed to tapis_uri_to_local_path().
**kwargs – Keyword arguments passed to tapis_uri_to_local_path().

Returns:

The corresponding DesignSafe local path (e.g., /home/jupyter/MyData/path).

Return type:

str

Example

>>> local_path = ds.files.to_path(
...     "tapis://designsafe.storage.default/user/data"
... )
>>> print(local_path)  # "/home/jupyter/MyData/data"

upload(*args, **kwargs)[source]¶

Upload a local file to a Tapis storage system.

This is a convenience wrapper around files_module.upload_file().

Parameters:

*args – Positional arguments passed to upload_file().
**kwargs – Keyword arguments passed to upload_file().

Raises:

FileOperationError – If the upload operation fails.
FileNotFoundError – If the local file does not exist.

download(*args, **kwargs)[source]¶

Download a file from a Tapis storage system to local filesystem.

This is a convenience wrapper around files_module.download_file().

Parameters:

*args – Positional arguments passed to download_file().
**kwargs – Keyword arguments passed to download_file().

Raises:

FileOperationError – If the download operation fails.

list(*args, **kwargs)[source]¶

List files and directories in a Tapis storage system path.

This is a convenience wrapper around files_module.list_files().

Parameters:

*args – Positional arguments passed to list_files().
**kwargs – Keyword arguments passed to list_files().

Returns:

List of file/directory objects from the specified path.

Return type:

List[Tapis]

Raises:

FileOperationError – If the listing operation fails.

class dapi.client.JobMethods(tapis_client)[source]¶

Bases: object

Interface for Tapis job submission, monitoring, and management.

This class provides methods for generating job requests, submitting jobs, monitoring job status, and managing submitted jobs.

Parameters:: tapis_client (Tapis) – Authenticated Tapis client instance.

parametric_sweep¶

Interface for PyLauncher parameter sweep generation.

Type:: ParametricSweepMethods

__init__(tapis_client)[source]¶

Initialize JobMethods with a Tapis client.

Parameters:: tapis_client (Tapis) – Authenticated Tapis client instance.

generate(app_id, input_dir_uri, script_filename=None, app_version=None, job_name=None, description=None, tags=None, max_minutes=None, node_count=None, cores_per_node=None, memory_mb=None, queue=None, allocation=None, archive_system=None, archive_path=None, extra_file_inputs=None, extra_app_args=None, extra_env_vars=None, extra_scheduler_options=None, script_param_names=['Input Script', 'Main Script', 'tclScript'], input_dir_param_name='Input Directory', allocation_param_name='TACC Allocation')[source]¶

Generate a Tapis job request dictionary based on app definition and inputs.

This method creates a properly formatted job request dictionary that can be submitted to Tapis. It automatically retrieves app details and applies user-specified overrides and extra parameters.

Parameters:

app_id (str) – The ID of the Tapis application to use for the job.
input_dir_uri (str) – Tapis URI to the input directory containing job files.
script_filename (str, optional) – Name of the main script file to execute. If None, no script parameter is added (suitable for apps like OpenFOAM).
app_version (str, optional) – Specific app version. If None, uses latest.
job_name (str, optional) – Custom job name. If None, auto-generates one.
description (str, optional) – Job description. If None, uses app description.
tags (List[str], optional) – List of tags to associate with the job.
max_minutes (int, optional) – Maximum runtime in minutes. Overrides app default.
node_count (int, optional) – Number of compute nodes. Overrides app default.
cores_per_node (int, optional) – Cores per node. Overrides app default.
memory_mb (int, optional) – Memory in MB. Overrides app default.
queue (str, optional) – Execution queue name. Overrides app default.
allocation (str, optional) – TACC allocation to charge for compute time.
archive_system (str, optional) – Archive system for job outputs. Use “designsafe” for designsafe.storage.default. If None, uses app default.
archive_path (str, optional) – Archive directory path. Can be a full path or just a directory name in MyData. If None and archive_system is “designsafe”, defaults to “tapis-jobs-archive/${JobCreateDate}/${JobUUID}”.
extra_file_inputs (List[Dict[str, Any]], optional) – Additional file inputs.
extra_app_args (List[Dict[str, Any]], optional) – Additional app arguments.
extra_env_vars (List[Dict[str, Any]], optional) – Additional environment variables.
extra_scheduler_options (List[Dict[str, Any]], optional) – Additional scheduler options.
script_param_names (List[str], optional) – Parameter names to check for script placement.
input_dir_param_name (str, optional) – Parameter name for input directory.
allocation_param_name (str, optional) – Parameter name for allocation.

Returns:

Complete job request dictionary ready for submission.

Return type:

Dict[str, Any]

Raises:

AppDiscoveryError – If the specified app cannot be found.
ValueError – If required parameters are missing or invalid.
JobSubmissionError – If job request generation fails.

Example

>>> job_request = ds.jobs.generate(
...     app_id="matlab-r2023a",
...     input_dir_uri="tapis://designsafe.storage.default/username/input/",
...     script_filename="run_analysis.m",
...     max_minutes=120,
...     allocation="MyProject-123",
... )

submit(job_request)[source]¶

Submit a job request dictionary to Tapis.

Takes a job request dictionary (typically from generate()) and submits it to Tapis for execution.

Parameters:

job_request (Dict[str, Any]) – Complete job request dictionary.

Returns:

A SubmittedJob object for monitoring and managing the job.

Return type:

SubmittedJob

Raises:

ValueError – If job_request is not a dictionary.
JobSubmissionError – If the Tapis submission fails.

Example

>>> job_request = ds.jobs.generate(...)
>>> job = ds.jobs.submit(job_request)
>>> print(f"Job submitted with UUID: {job.uuid}")

job(job_uuid)[source]¶

Get a SubmittedJob object for an existing job by UUID.

Parameters:: job_uuid (str) – The UUID of an existing Tapis job.
Returns:: A job object for monitoring via .monitor().
Return type:: SubmittedJob

Example

>>> job = ds.jobs.job("12345678-1234-1234-1234-123456789abc")
>>> job.monitor()

status(job_uuid)[source]¶

Get the current status of a job by UUID.

Parameters:: job_uuid (str) – The UUID of the job to check.
Returns:: The current job status (e.g., “QUEUED”, “RUNNING”, “FINISHED”).
Return type:: str
Raises:: JobMonitorError – If status retrieval fails.

Example

>>> ds.jobs.status("12345678-1234-1234-1234-123456789abc")
'FINISHED'

runtime_summary(job_uuid, verbose=False)[source]¶

Print the runtime summary for a job by UUID.

Parameters:

job_uuid (str) – The UUID of the job to analyze.
verbose (bool, optional) – If True, prints detailed job history events. Defaults to False.

Example

>>> ds.jobs.runtime_summary("12345678-1234-1234-1234-123456789abc")
Runtime Summary
---------------
QUEUED  time: 00:05:30
RUNNING time: 01:23:45
TOTAL   time: 01:29:15

interpret_status(final_status, job_uuid=None)[source]¶

Print a user-friendly interpretation of a job status.

Parameters:

final_status (str) – The job status to interpret.
job_uuid (str, optional) – The job UUID for context in the message.

Example

>>> ds.jobs.interpret_status(
...     "FINISHED", "12345678-1234-1234-1234-123456789abc"
... )
Job 12345678-1234-1234-1234-123456789abc completed successfully.

list(app_id=None, status=None, limit=100, output='df', verbose=False)[source]¶

List jobs with optional filtering.

Fetches jobs from Tapis ordered by creation date (newest first). Filters are applied client-side.

Parameters:

app_id (str, optional) – Filter by application ID.
status (str, optional) – Filter by job status (e.g., “FINISHED”). Case-insensitive.
limit (int, optional) – Maximum jobs to fetch. Defaults to 100.
output (str, optional) – Output format. “df” for pandas DataFrame (default), “list” for list of dicts, “raw” for TapisResult objects.
verbose (bool, optional) – Print job count. Defaults to False.

Returns:

DataFrame, list of dicts, or list of TapisResult objects.

Return type:

Depends on output

Raises:

JobMonitorError – If the Tapis API call fails.

Example

>>> df = ds.jobs.list(app_id="matlab-r2023a", status="FINISHED")
>>> jobs = ds.jobs.list(output="list")
>>> raw = ds.jobs.list(limit=10, output="raw")

class dapi.client.SystemMethods(tapis_client)[source]¶

Bases: object

Interface for Tapis system information and queue management.

This class provides methods for retrieving information about Tapis execution systems and their available job queues.

Parameters:: tapis_client (Tapis) – Authenticated Tapis client instance.

__init__(tapis_client)[source]¶

Initialize SystemMethods with a Tapis client.

Parameters:: tapis_client (Tapis) – Authenticated Tapis client instance.

queues(system_id, verbose=True)[source]¶

List logical queues available on a Tapis execution system.

This is a convenience wrapper around systems_module.list_system_queues().

Parameters:

system_id (str) – The ID of the execution system (e.g., ‘frontera’).
verbose (bool, optional) – If True, prints detailed queue information. Defaults to True.

Returns:

List of queue objects with queue configuration details.

Return type:

List[Any]

Raises:

SystemInfoError – If the system is not found or queue retrieval fails.
ValueError – If system_id is empty.

check_credentials(system_id, username=None)[source]¶

Check whether TMS credentials exist for a user on a system.

Parameters:

system_id (str) – The ID of the Tapis system (e.g., ‘frontera’).
username (str, optional) – Username to check. Defaults to the authenticated user.

Returns:

True if credentials exist, False otherwise.

Return type:

bool

Raises:

CredentialError – If the credential check fails unexpectedly.
ValueError – If system_id is empty.

establish_credentials(system_id, username=None, force=False, verbose=True)[source]¶

Establish TMS credentials for a user on a Tapis system.

Idempotent: skips creation if credentials already exist (unless force=True). Only supported for systems using TMS_KEYS authentication.

Parameters:

system_id (str) – The ID of the Tapis system (e.g., ‘frontera’).
username (str, optional) – Username. Defaults to the authenticated user.
force (bool, optional) – Re-create even if credentials exist. Defaults to False.
verbose (bool, optional) – Print status messages. Defaults to True.

Raises:

CredentialError – If the system is not TMS_KEYS or creation fails.
ValueError – If system_id is empty.

Return type:

None

revoke_credentials(system_id, username=None, verbose=True)[source]¶

Remove TMS credentials for a user on a Tapis system.

Idempotent: succeeds silently if credentials do not exist.

Parameters:

system_id (str) – The ID of the Tapis system (e.g., ‘frontera’).
username (str, optional) – Username. Defaults to the authenticated user.
verbose (bool, optional) – Print status messages. Defaults to True.

Raises:

CredentialError – If credential removal fails unexpectedly.
ValueError – If system_id is empty.

Return type:

None

class dapi.client.ParametricSweepMethods(tapis_client)[source]¶

Bases: object

Interface for PyLauncher parameter sweeps.

generate — preview (preview=True) or write sweep files.
submit — submit the sweep job to TACC.

generate(command, sweep, directory=None, *, placeholder_style='token', debug=None, preview=False)[source]¶

Generate PyLauncher sweep files or preview the parameter grid.

With preview=True, returns a DataFrame of all parameter combinations — no files are written.

Otherwise, expands command into one command per combination and writes runsList.txt and call_pylauncher.py into directory. Returns the list of generated commands.

Parameters:

command (str) – Command template with placeholders matching sweep keys.
sweep (Dict[str, Any]) – Mapping of placeholder name to sequence of values.
directory (str) – Directory to write files into (created if needed). Required when preview is False.
placeholder_style (str) – "token" (default) for bare ALPHA, or "braces" for {ALPHA}.
debug (str) – Optional debug string (e.g. "host+job").
preview (bool) – If True, return a DataFrame (dry run).

Returns:

List[str] of commands, or pandas.DataFrame when preview is True.

submit(directory, app_id, allocation, *, node_count=None, cores_per_node=None, max_minutes=None, queue=None, archive_system='designsafe', archive_path=None, **kwargs)[source]¶

Submit a PyLauncher sweep job.

Translates directory to a Tapis URI, builds a job request with call_pylauncher.py as the script, and submits it.

Archives to the user’s DesignSafe storage by default (not the app’s archive path, which may belong to the app owner).

Parameters:

directory (str) – Path to the input directory containing runsList.txt and call_pylauncher.py (e.g. "/MyData/sweep/").
app_id (str) – Tapis application ID (e.g. "designsafe-agnostic-app").
allocation (str) – TACC allocation to charge.
node_count (int | None) – Number of compute nodes.
cores_per_node (int | None) – Cores per node.
max_minutes (int | None) – Maximum runtime in minutes.
queue (str | None) – Execution queue name.
archive_system (str | None) – Archive system. Defaults to "designsafe" (the user’s own storage).
archive_path (str | None) – Archive directory path. If None, uses the default tapis-jobs-archive/ under the user’s MyData.
**kwargs – Additional arguments passed to ds.jobs.generate().

Returns:

A job object for monitoring via .monitor().

Return type:

SubmittedJob