docs: def auth(alias=None, url=None, cfg="~/.xnat_auth"):
      '''
      Read connection details from an xnat_auth XML file
  
      Example:
          >>> import yaxil
          >>> auth = yaxil.auth('xnatastic')
          >>> auth.url, auth.username, auth.password
          ('https://www.xnatastic.org/', 'username', '********')
  
      :param alias: XNAT alias
      :type alias: str
      :param url: XNAT URL
      :type url: str
      :param cfg: Configuration file
      :type cfg: str
      :returns: Named tuple of (url, username, password)
      :rtype: :mod:`yaxil.XnatAuth`
      '''
      if not alias and not url:
          raise ValueError('you must provide an alias or url argument')
      if alias and url:
          raise ValueError('cannot provide both alias and url arguments')
      # check and parse config file
      cfg = os.path.expanduser(cfg)
      if not os.path.exists(cfg):
          raise AuthError("could not locate auth file %s" % cfg)
      tree = etree.parse(os.path.expanduser(cfg))
      # search by alias or url
      res = None
      if alias:
          res = tree.findall("./%s" % alias)
      if url:
          res = tree.findall("./*/[url='%s']" % url)
      if not res:
          raise AuthError("failed to locate xnat credentials within %s" % cfg)
      elif len(res) > 1:
          raise AuthError("found too many sets of credentials within %s" % cfg)
      res = res.pop()
      # get url
      url = res.findall("url")
      if not url:
          raise AuthError("no url for %s in %s" % (alias, cfg))
      elif len(url) > 1:
          raise AuthError("too many urls for %s in %s" % (alias, cfg))
      # get username
      username = res.findall("username")
      if not username:
          raise AuthError("no username for %s in %s" % (alias, cfg))
      elif len(username) > 1:
          raise AuthError("too many usernames for %s in %s" % (alias, cfg))
      # get password
      password = res.findall("password")
      if not password:
          raise AuthError("no password for %s in %s" % (alias, cfg))
      elif len(password) > 1:
          raise AuthError("too many passwords for %s in %s" % (alias, cfg))
      return XnatAuth(url=url.pop().text, username=username.pop().text, 
                          password=password.pop().text)