2.1. dxpy Object Handlers

The DXObject class is the abstract base class for all remote object handlers, and its subclass DXDataObject is the abstract base class for all remote data object handlers.

dxpy.bindings.verify_string_dxid(dxid, expected_classes)

Parameters:

• dxid – Value to verify as a DNAnexus ID of class expected_class

• expected_classes (string or list of strings) – Single string or list of strings of allowed classes of the ID, e.g. “file” or [“project”, “container”]

Raises:

DXError if dxid is not a string or is not a valid DNAnexus ID of the expected class

class dxpy.bindings.DXObject(dxid=None, project=None)

Bases: object

Abstract base class for all remote object handlers.

describe(*args, **kwargs)

Avoid infinite recursion in __getattr__ if describe is not defined.

set_id(dxid)

Parameters:

dxid (string) – New ID to be associated with the handler

Discards the currently stored ID and associates the handler with dxid

get_id()

Returns:

ID of the associated object

Return type:

string

Returns the ID that the handler is currently associated with.

class dxpy.bindings.DXDataObject(dxid=None, project=None)

Bases: DXObject

Abstract base class for all remote data object handlers.

Note

The attribute values below are current as of the last time describe() was run. (Access to any of the below attributes causes describe() to be called if it has never been called before.)

name

String giving the name of the object

folder

String giving the full path to the folder containing the object

types

List of strings indicating the types associated with the object

state

A string containing one of the values “open”, “closing”, or “closed”

hidden

Boolean indicating whether the object is hidden or not

links

List of strings indicating object IDs that are pointed to by the object

sponsored

Boolean indicating whether the object is sponsored by DNAnexus

tags

List of strings indicating the tags that are assocated with the object

created

Timestamp at which the object was created, in milliseconds since January 1, 1970 at midnight (UTC).

modified

Timestamp at which the object was last modified, in milliseconds since January 1, 1970 at midnight (UTC).

createdBy

dict containing the following keys and values:

• user: the string ID of the user who created the object or launched the job that created it

• job (optional): the string ID of the job that created the object, if a job created the object

• executable (optional): the string ID of the app or applet that the job was running, if a job created the object

new(**kwargs)

Parameters:

• project (string) – Project ID in which to create the new remote object

• name (string) – Name for the object

• tags (list of strings) – Tags to add for the object

• types (list of strings) – Types to add to the object

• hidden (boolean) – Whether the object is to be hidden

• properties (dict) – Properties given as key-value pairs of strings

• details (dict or list) – Details to set for the object

• folder (string) – Full path to the destination folder

• parents (boolean) – If True, recursively create all parent folders if they are missing

Return type:

DXDataObject

Creates a data object with the given fields. Only project is required, and only if no default project or workspace is set; the remaining arguments are optional and have default behavior as specified in the API documentation for the /new method of each data object class.

set_id(dxid)

Parameters:

dxid (string or dict) – Object ID or a DNAnexus link (a dict with key “$dnanexus_link”); if a project ID is provided in the DNAnexus link, it will also be used to set the project ID

Equivalent to calling set_ids() with the same arguments.

set_ids(dxid, project=None)

Parameters:

• dxid (string or dict) – Object ID or a DNAnexus link (a dict with key “$dnanexus_link”); if a project ID is provided in the DNAnexus link, it will be used as project unless project has been explictly provided

• project (string) – Project ID

Discards the currently stored ID and associates the handler with dxid. Associates the handler with the copy of the object in project (if no project is explicitly specified, the default data container is used).

get_proj_id()

Returns:

Project ID of associated object

Return type:

string

Returns the project ID, if any, that the handler is currently associated with.

describe(incl_properties=False, incl_details=False, fields=None, default_fields=None, **kwargs)

Parameters:

• fields (set or sequence of str) – set of fields to include in the output, for example {'name', 'modified'}. The field id is always implicitly included. If fields is specified, the default fields are not included (that is, only the fields specified here, and id, are included) unless default_fields is additionally set to True.

• default_fields (bool) – if True, include the default fields in addition to fields requested in fields, if any; if False, only the fields specified in fields, if any, are returned (defaults to False if fields is specified, True otherwise)

• incl_properties (bool) – if true, includes the properties of the object in the output (deprecated; use fields={'properties'}, default_fields=True instead)

• incl_details (bool) – if true, includes the details of the object in the output (deprecated; use fields={'details'}, default_fields=True instead)

Returns:

Description of the remote object

Return type:

dict

Return a dict with a description of the remote data object.

The result includes the key-value pairs as specified in the API documentation for the /describe method of each data object class. The API defines some default set of fields that will be included (at a minimum, “id”, “class”, etc. should be available, and there may be additional fields that vary based on the class); the set of fields may be customized using fields and default_fields.

Any project-specific metadata fields (name, properties, and tags) are obtained from the copy of the object in the project associated with the handler, if possible.

add_types(types, **kwargs)

Parameters:

types (list of strings) – Types to add to the object

Raises:

DXAPIError if the object is not in the “open” state

Adds each of the specified types to the remote object. Takes no action for types that are already listed for the object.

remove_types(types, **kwargs)

Parameters:

types (list of strings) – Types to remove from the object

Raises:

DXAPIError if the object is not in the “open” state

Removes each the specified types from the remote object. Takes no action for types that the object does not currently have.

get_details(**kwargs)

Returns the contents of the details of the object.

Return type:

list or dict

set_details(details, **kwargs)

Parameters:

details (dict or list) – Details to set for the object

Raises:

DXAPIError if the object is not in the “open” state

Sets the details for the remote object with the specified value. If the input contains the string "$dnanexus_link" as a key in a hash, it must be the only key in the hash, and its value must be a valid ID of an existing object.

hide(**kwargs)

Raises:

DXAPIError if the object is not in the “open” state

Hides the remote object.

unhide(**kwargs)

Raises:

DXAPIError if the object is not in the “open” state

Makes the remote object visible.

rename(name, **kwargs)

Parameters:

name (string) – New name for the object

Renames the remote object.

The name is changed on the copy of the object in the project associated with the handler.

get_properties(**kwargs)

Returns:

Properties given as key-value pairs of strings

Return type:

dict

Returns the properties of the object.

The properties are read from the copy of the object in the project associated with the handler.

set_properties(properties, **kwargs)

Parameters:

properties (dict) – Property names and values given as key-value pairs of strings

Given key-value pairs in properties for property names and values, the properties are set on the object for the given property names. Any property with a value of None indicates the property will be deleted.

Note

Any existing properties not mentioned in properties are not modified by this method.

The properties are written to the copy of the object in the project associated with the handler.

The following example sets the properties for “name” and “project” for a remote file:

dxfile.set_properties({"name": "George", "project": "cancer"})

Subsequently, the following would delete the property “project”:

dxfile.set_properties({"project": None})

add_tags(tags, **kwargs)

Parameters:

tags (list of strings) – Tags to add to the object

Adds each of the specified tags to the remote object. Takes no action for tags that are already listed for the object.

The tags are added to the copy of the object in the project associated with the handler.

remove_tags(tags, **kwargs)

Parameters:

tags (list of strings) – Tags to remove from the object

Removes each of the specified tags from the remote object. Takes no action for tags that the object does not currently have.

The tags are removed from the copy of the object in the project associated with the handler.

close(**kwargs)

Closes the object for further modification to its types, details, visibility, and contents.

list_projects(**kwargs)

Return type:

list of strings

Returns a list of project IDs of the projects that contain this object and are visible to the requesting user.

remove(**kwargs)

Raises:

DXError if no project is associated with the object

Permanently removes the associated remote object from the associated project.

move(folder, **kwargs)

Parameters:

folder (string) – Folder route to which to move the object

Raises:

DXError if no project is associated with the object

Moves the associated remote object to folder.

clone(project, folder='/', **kwargs)

Parameters:

• project (string) – Destination project ID

• folder (string) – Folder route to which to move the object

Raises:

DXError if no project is associated with the object

Returns:

An object handler for the new cloned object

Return type:

DXDataObject

Clones the associated remote object to folder in project and returns an object handler for the new object in the destination project.