Client

class dapi.client.DSClient(tapis_client=None, **auth_kwargs)

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

projects

Interface for DesignSafe project management.

Type:

ProjectMethods

publications

Interface for published datasets.

Type:

PublicationMethods

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)

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)

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)

Initialize AppMethods with a Tapis client.

Parameters:

tapis_client (Tapis) – Authenticated Tapis client instance.

find(*args, **kwargs)

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)

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.

templates()

Names of the app templates that ship with dapi.

Return type:

List[str]

new(*args, **kwargs)

Write the files for a new Tapis app from a dapi template.

Convenience wrapper around apps_module.new_app(). Creates <target_dir>/<app_id>/ with app.json and tapisjob_app.sh ready to edit, then register with ds.apps.deploy().

Returns:

Path of the created app directory.

Return type:

str

deploy(*args, **kwargs)

Register (or update) a user-owned Tapis app from an app directory.

Convenience wrapper around apps_module.deploy_app(): zips the wrapper, uploads it to your storage, and registers the app version under your ownership. Rerunning with the same version updates the app in place.

Returns:

app_id, version, and container_image.

Return type:

dict

class dapi.client.FileMethods(tapis_client)

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)

Initialize FileMethods with a Tapis client.

Parameters:

tapis_client (Tapis) – Authenticated Tapis client instance.

to_uri(*args, **kwargs)

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)

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)

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)

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)

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)

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)

Initialize JobMethods with a Tapis client.

Parameters:

tapis_client (Tapis) – Authenticated Tapis client instance.

prepare_inputs(app_id, input_dir, staging_destination='/MyData/dapi-staging', **options)

Prepare a local input directory for an app before staging.

Dispatches to the app’s profile when one is registered; a no-op beyond existence checking for apps that need no preparation. For SimCenter apps (simcenter-*) this rewrites the workflow JSON’s backend paths, reports the UQ engine, random variables, and EDPs, and by default bundles the inputs into a single tmpSimCenter.zip (unpacked natively by the app wrapper) so staging transfers one file instead of many. Stage the returned staged_dir.

The returned staged_dir is always stageable. Local staging uses fast local disk (a temporary directory for read-only sources like CommunityData); Tapis jobs can only pull inputs from Tapis storage, so when the staged directory is not visible to Tapis the files are uploaded once, over the Tapis files API, to staging_destination (default /MyData/dapi-staging — dapi’s notation for tapis://designsafe.storage.default/<username>/dapi-staging, the storage every DesignSafe account has; this is a remote upload, not a local path — no MyData mount or Jupyter environment is assumed). staged_dir is returned as the full tapis:// URL — ds.files.to_uri(info["staged_dir"]) passes it through unchanged — and the local copy is reported as local_staged_dir. Pass any translatable DesignSafe path (e.g. a project path) as staging_destination to upload elsewhere.

Parameters:

• app_id (str) – The Tapis app id the inputs are being prepared for.

• input_dir (str) – Local path to the job input directory.

• **options (Any) – Profile-specific options (e.g. backend_dir, input_filename, bundle=False for SimCenter apps).

• staging_destination (str)

• **options

Returns:

Summary of the preparation performed. Always

includes staged_dir — the directory to stage.

Return type:

Dict[str, Any]

Example

>>> info = ds.jobs.prepare_inputs("simcenter-uq-stampede3", "./DS_input")
>>> input_uri = ds.files.to_uri(info["staged_dir"])

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')

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)

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)

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)

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)

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)

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, list_type='MY_JOBS')

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.

• list_type (str, optional) – “MY_JOBS” (default) for jobs you own, “SHARED_JOBS” for jobs shared with you, “ALL_JOBS” for both.

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)

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)

Initialize SystemMethods with a Tapis client.

Parameters:

tapis_client (Tapis) – Authenticated Tapis client instance.

list(category=None, output='df')

List Tapis systems you have access to.

Filters out internal and project-specific systems by default.

Parameters:

• category (str, optional) – “hpc” for execution systems, “storage” for storage systems, “all” for everything, None for HPC + storage (default).

• output (str, optional) – “df” for DataFrame (default), “list” for dicts.

Returns:

Systems with id, host, category, authn, credentials.

Return type:

DataFrame or List[Dict]

Example

>>> ds.systems.list()  # HPC + storage
>>> ds.systems.list("hpc")  # HPC only with credential status
>>> ds.systems.list("storage")  # Storage only
>>> ds.systems.list("all")  # Everything including internal

queues(system_id, output='df')

List batch queues available on a Tapis execution system.

Parameters:

• system_id (str) – The ID of the execution system (e.g., “stampede3”).

• output (str, optional) – “df” for DataFrame (default), “raw” for Tapis objects.

Returns:

Queues with name, maxNodes, maxMinutes, etc.

Return type:

DataFrame or List

Example

>>> ds.systems.queues("stampede3")

check_credentials(system_id, username=None)

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)

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)

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)

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)

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. With the default "token" style, a placeholder is replaced everywhere it appears as a word — so a single-letter name like E also matches inside a --E flag. Use distinct names (EMOD, not E) or placeholder_style="braces".

• 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, staging_destination='/MyData/dapi-staging', **kwargs)

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.

A directory that is not a recognizable DesignSafe path (a local folder on a laptop or CI runner, or a temp dir outside the JupyterHub mounts) is uploaded once over the Tapis files API to staging_destination and submitted from there, matching the prepare_inputs behavior.

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. "python-s3").

• 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.

• staging_destination (str) – DesignSafe path that receives a one-time upload when directory is local-only. Defaults to /MyData/dapi-staging.

• **kwargs – Additional arguments passed to ds.jobs.generate().

Returns:

A job object for monitoring via .monitor().

Return type:

SubmittedJob