'''

These functions provide shorthand functional interfaces for actions such
as getting a :class:`~dxpy.bindings.DXDataObject` handler from an ID or
`link
<http://wiki.dnanexus.com/API-Specification-v1.0.0/Details-and-Links#Linking>`_,
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.

'''

from dxpy.bindings import *

def dxlink(object_id, project_id=None):
    '''
    :param object_id: Object ID or the object handler itself
    :type object_id: string or :class:`~dxpy.bindings.DXDataObject`
    :param project_id: A project ID, if creating a cross-project DXLink
    :type project_id: string

    Creates a DXLink (a dict formatted as a symbolic DNAnexus object
    reference) to the specified object.
    '''
    if isinstance(object_id, DXDataObject):
        object_id = object_id.get_id()
    if project_id is None:
        return {'$dnanexus_link': object_id}
    else:
        return {'$dnanexus_link': {'project': project_id, 'id': object_id}}

def is_dxlink(x):
    '''
    :param x: A potential DNAnexus link

    Returns whether *x* appears to be a DNAnexus link (is a dict with
    key ``"$dnanexus_link"``).
    '''
    return isinstance(x, dict) and '$dnanexus_link' in x

def get_dxlink_ids(link):
    '''
    :param link: A DNAnexus link
    :type link: dict
    :returns: Object ID, Project ID (or :const:`None` if no project specified in the link)
    :rtype: tuple

    Returns the object and project IDs stored in the given DNAnexus
    link.
    '''
    if isinstance(link['$dnanexus_link'], dict):
        return link['$dnanexus_link']['id'], link['$dnanexus_link']['project']
    else:
        return link['$dnanexus_link'], None

def _guess_link_target_type(link):
    if is_dxlink(link):
        link = link['$dnanexus_link']
    class_name, _id = link.split("-")
    class_name = 'DX'+class_name.capitalize()
    if class_name == 'DXGtable':
        class_name = 'DXGTable'
    cls = dxpy.__dict__[class_name]
    return cls

def get_handler(link, project=None):
    '''
    :param link: String containing an object ID or dict containing a DXLink
    :rtype: :class:`~dxpy.bindings.DXDataObject`

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

    Example::

        get_handler("gtable-1234").get_col_names()
    '''
    try:
        cls = _guess_link_target_type(link)
        if project is not None:
            return cls(link, project=project)
        else:
            return cls(link)
    except Exception as e:
        raise DXError("Could not parse link "+str(link))

def describe(link, **kwargs):
    '''
    :param link: String containing an object ID or dict containing a DXLink

    Given an object ID, calls :meth:`~dxpy.bindings.DXDataObject.describe` on the object.

    Example::

        describe("file-1234")
    '''
    handler = get_handler(link)
    return handler.describe(**kwargs)

def get_details(link, **kwargs):
    '''
    :param link: String containing an object ID or dict containing a DXLink

    Given an object ID, calls :meth:`~dxpy.bindings.DXDataObject.get_details` on the object.

    Example::

        get_details("file-1234")
    '''
    handler = get_handler(link)
    return handler.get_details(**kwargs)

def remove(link, **kwargs):
    '''
    :param link: String containing an object ID or dict containing a DXLink

    Given an object ID, calls :meth:`~dxpy.bindings.DXDataObject.remove` on the object.

    Example::

        remove("file-1234")
    '''
    handler = get_handler(link)
    return handler.remove(**kwargs)

@@ -2080,24 +2080,30 @@
 get_handler(
+id_or_
 link, projec
@@ -2122,32 +2122,38 @@
  '''%0A    :param 
+id_or_
 link: String con
@@ -2451,24 +2451,30 @@
 target_type(
+id_or_
 link)%0A      
@@ -2518,24 +2518,30 @@
  return cls(
+id_or_
 link, projec
@@ -2588,16 +2588,22 @@
 urn cls(
+id_or_
 link)%0A  
@@ -2677,16 +2677,22 @@
 k %22+str(
+id_or_
 link))%0A%0A
@@ -2704,16 +2704,22 @@
 escribe(
+id_or_
 link, **
@@ -2738,32 +2738,38 @@
  '''%0A    :param 
+id_or_
 link: String con
@@ -2980,32 +2980,38 @@
 r = get_handler(
+id_or_
 link)%0A    return
@@ -3055,16 +3055,22 @@
 details(
+id_or_
 link, **
@@ -3089,32 +3089,38 @@
  '''%0A    :param 
+id_or_
 link: String con
@@ -3337,32 +3337,38 @@
 r = get_handler(
+id_or_
 link)%0A    return
@@ -3410,16 +3410,22 @@
  remove(
+id_or_
 link, **
@@ -3448,24 +3448,30 @@
 %0A    :param 
+id_or_
 link: String
@@ -3690,16 +3690,22 @@
 handler(
+id_or_
 link)%0A  

Rename link param to id_or_link where appropriate.