2.2. Utility Functions

These functions provide shorthand functional interfaces for actions such as getting a DXDataObject handler from an ID or link, or creating a link from a handler. In addition, there are functions for performing simple actions with an ID or link as input without creating a full object handler.

dxpy.bindings.dxdataobject_functions.dxlink(object_id, project_id=None, field=None)

Parameters:

• object_id (string or DXDataObject) – Object ID or the object handler itself
• project_id (string) – A project ID, if creating a cross-project DXLink
• field (string) – A field name, if creating a job-based object reference

Returns:

A dict formatted as a symbolic DNAnexus object reference

Return type:

dict

Creates a DXLink to the specified object.

If object_id is already a link, it is returned without modification.

If object_id is a `~dxpy.bindings.DXDataObject, the object ID is retrieved via its get_id() method.

If field is not None, object_id is expected to be of class ‘job’ and the link created is a Job Based Object Reference (JBOR), which is of the form:

{'$dnanexus_link': {'job': object_id, 'field': field}}

If field is None and project_id is not None, the link created is a project-specific link of the form:

{'$dnanexus_link': {'project': project_id, 'id': object_id}}

dxpy.bindings.dxdataobject_functions.is_dxlink(x)

Parameters:x – A potential DNAnexus link

Returns whether x appears to be a DNAnexus link (is a dict with key "$dnanexus_link") with a referenced data object.

dxpy.bindings.dxdataobject_functions.get_dxlink_ids(link)

Parameters:link (dict) – A DNAnexus link Returns:(Object ID, Project ID) if the link is to a data object (or None if no project specified in the link), or (Job ID, Field) if the link is a job-based object reference (JBOR). Return type:tuple

Get the object ID and detail from a link. There are three types of links:

• Simple link of the form {"$dnanexus_link": "file-XXXX"} returns ("file-XXXX", None).
• Data object link of the form {"$dnanexus_link': {"id": "file-XXXX", "project": "project-XXXX"}} returns ("file-XXXX", "project-XXXX").
• Job-based object reference (JBOR) of the form {"$dnanexus_link": {"job": "job-XXXX", "field": "foo"}} returns ("job-XXXX", "foo").

dxpy.bindings.dxdataobject_functions.get_handler(id_or_link, project=None)

Parameters:

• id_or_link (string or dict) – String containing an object ID or dict containing a DXLink
• project (string) – String project ID to use as the context if the the object is a data object

Return type:

DXObject, DXApp, or DXGlobalWorkflow

Parses a string or DXLink dict. Creates and returns an object handler for it.

Example:

get_handler("file-1234")

dxpy.bindings.dxdataobject_functions.describe(id_or_link, **kwargs)

Parameters:id_or_link – String containing an object ID or dict containing a DXLink, or a list of object IDs or dicts containing a DXLink.

Given an object ID, calls describe() on the object.

Example:

describe("file-1234")

Given a list of object IDs, calls system_describe_data_objects().

Example:

describe(["file-1234", "workflow-5678"])

Note: If id_or_link is a list and **kwargs contains a “fields” parameter, these fields will be returned in the response for each data object in addition to the fields included by default. Additionally, describe options can be provided for each data object class in the “classDescribeOptions” kwargs argument. See https://documentation.dnanexus.com/developer/api/system-methods#api-method-system-describedataobjects for input parameters used with the multiple object describe method.

dxpy.bindings.dxdataobject_functions.get_details(id_or_link, **kwargs)

Parameters:id_or_link – String containing an object ID or dict containing a DXLink

Given an object ID, calls get_details() on the object.

Example:

get_details("file-1234")

dxpy.bindings.dxdataobject_functions.remove(id_or_link, **kwargs)

Parameters:id_or_link – String containing an object ID or dict containing a DXLink

Given an object ID, calls remove() on the object.

Example:

remove("file-1234")