3. dxpy.app_builder Module

This module contains high-level subroutines for creating app and applet objects.

If you are developing apps, we strongly recommend that you use the command-line application builder tool dx build to compile and deploy applets and apps onto the platform. (Those command-line tools are implemented using the methods in this module.)

Warning

This module is mostly intended for DNAnexus internal use. You probably only need to use the methods here directly if you are implementing a specialized development or publishing workflow that is not supported by the stock command-line builders.

3.1. App Builder Library

Contains utility methods useful for compiling and deploying applets and apps onto the platform.

You can specify the destination project in the following ways (with the earlier ones taking precedence):

  • Supply the project argument to upload_resources() or upload_applet().

  • Supply the ‘project’ attribute in your dxapp.json.

  • Set the DX_WORKSPACE_ID environment variable (when running in a job context).

You can use the function get_destination_project() to determine the effective destination project.

exception dxpy.app_builder.AppBuilderException[source]

Bases: Exception

This exception is raised by the methods in this module when app or applet building fails.

dxpy.app_builder.build(src_dir, parallel_build=True)[source]

Runs any build scripts that are found in the specified directory.

In particular, runs ./configure if it exists, followed by make -jN if it exists (building with as many parallel tasks as there are CPUs on the system).

dxpy.app_builder.get_destination_project(src_dir, project=None)[source]
Returns:

Project ID where applet specified by src_dir would be written

Return type:

str

Returns the project ID where the applet specified in src_dir (or its associated resource bundles) would be written. This returns the same project that would be used by upload_resources() and upload_applet(), given the same src_dir and project parameters.

Parameters:

link_target (string) – The target of a symbolic link, as given by os.readlink()

Returns:

A boolean indicating the link is local to the current directory. This is defined to mean that os.path.isabs(link_target) == False and the link NEVER references the parent directory, so “./foo/../../curdir/foo” would return False.

Return type:

boolean

dxpy.app_builder.upload_resources(src_dir, project=None, folder='/', ensure_upload=False, force_symlinks=False, brief=False, resources_dir=None, worker_resources_subpath='')[source]
Parameters:

  • ensure_upload (boolean) – If True, will bypass checksum of resources directory and upload resources bundle unconditionally; will NOT be able to reuse this bundle in future builds. Else if False, will compute checksum and upload bundle if checksum is different from a previously uploaded bundle’s checksum.

  • force_symlinks (boolean) – If true, will bypass the attempt to dereference any non-local symlinks and will unconditionally include the link as-is. Note that this will almost certainly result in a broken link within the resource directory unless you really know what you’re doing.

  • resources_dir (str) – Directory with resources to be archived and uploaded. If not given, uses resources/.

  • worker_resources_subpath (str) – Path that will be prepended to the default directory where files are extracted on the worker. Default is empty string, therefore files would be extracted directly to the root folder. Example: If “home/dnanexus” is given, files will be extracted into /home/dnanexus.

Returns:

A list (possibly empty) of references to the generated archive(s)

Return type:

list

If resources_dir exists, archives and uploads the contents of the resources_dir (usually resources/) subdirectory of src_dir to a new remote file object, and returns a list describing a single bundled dependency in the form expected by the bundledDepends field of a run specification. Returns an empty list, if no archive was created.

dxpy.app_builder.upload_applet(src_dir, uploaded_resources, check_name_collisions=True, overwrite=False, archive=False, project=None, override_folder=None, override_name=None, dry_run=False, brief=False, **kwargs)[source]

Creates a new applet object.

Parameters:

  • project (str, or None to use whatever is specified in dxapp.json) – ID of container in which to create the applet.

  • override_folder (str) – folder name for the resulting applet which, if specified, overrides that given in dxapp.json

  • override_name (str) – name for the resulting applet which, if specified, overrides that given in dxapp.json

dxpy.app_builder.create_app_multi_region(regional_options, app_name, src_dir, publish=False, set_default=False, billTo=None, try_versions=None, try_update=True, confirm=True, inherited_metadata={}, brief=False)[source]

Creates a new app object from the specified applet(s).

Parameters:

regional_options (dict) – Region-specific options for the app. See https://documentation.dnanexus.com/developer/api/running-analyses/apps#api-method-app-new for details; this should contain keys for each region the app is to be enabled in, and for the values, a dict containing (at minimum) a key “applet” whose value is an applet ID for that region.

dxpy.app_builder.create_app(applet_id, applet_name, src_dir, publish=False, set_default=False, billTo=None, try_versions=None, try_update=True, confirm=True, regional_options=None)[source]

Creates a new app object from the specified applet.

Deprecated since version 0.204.0: Use create_app_multi_region() instead.

dxpy.app_builder.get_enabled_regions(app_spec, from_command_line)[source]

Returns a list of the regions in which the app should be enabled.

Also validates that app_spec[‘regionalOptions’], if supplied, is well-formed.

Parameters:

  • app_spec (dict) – app specification

  • from_command_line (list or None) – The regions specified on the command-line via –region