def search(self, q, limit=None, offset=None, resource_type=None,
search_domain=None, **params):
"""
Perform a simple ``GET`` based search.
Does not support all of the behaviors and parameters of advanced
searches.
**Parameters**
``q`` (*string*)
The user-query string. Required for simple searches (and most
advanced searches).
``search_domain`` (*string*)
Optional unless ``default_search_domain`` was not set.
The domain to query.
``limit`` (*int*)
Optional. The number of results to return.
``offset`` (*int*)
Optional. An offset into the total result set for paging.
``resource_type`` (*string*)
Optional. A resource_type name as defined within the DataSearch
service.
``params``
Any aditional query params to pass. For internal use only.
"""
uri = self._resolve_uri('/v1/search', search_domain)
merge_params(params, q=q, limit=limit, offset=offset,
resource_type=resource_type)
return self.get(uri, params=params)
def get_entry(self, index_id, subject, entry_id=None, **params):
"""
``GET /v1/index/<index_id>/entry``
**Examples**
Lookup the entry with a subject of ``https://example.com/foo/bar`` and
a null entry_id:
>>> sc = globus_sdk.SearchClient(...)
>>> entry_data = sc.get_entry(index_id, 'http://example.com/foo/bar')
Lookup the entry with a subject of ``https://example.com/foo/bar`` and
an entry_id of ``foo/bar``:
>>> sc = globus_sdk.SearchClient(...)
>>> entry_data = sc.get_entry(index_id, 'http://example.com/foo/bar',
>>> entry_id='foo/bar')
**External Documentation**
See
`Get Entry \
<https://docs.globus.org/api/search/entry_ops/#get_single_entry>`_
in the API documentation for details.
"""
index_id = safe_stringify(index_id)
merge_params(params, subject=subject, entry_id=entry_id)
self.logger.info("SearchClient.get_entry({}, {}, {}, ...)".format(
index_id, subject, entry_id))
path = self.qjoin_path("v1/index", index_id, "entry")
return self.get(path, params=params)
def create_group(self, name, description, **params):
"""
:rtype: GlobusResponse
"""
merge_params(params, name=name, description=description)
self.logger.debug("NexusClient.create_group({})".format(params))
return self.post('/groups', json_body=params)
def delete_entry(self, index_id, subject, entry_id=None, **params):
"""
``DELETE /v1/index/<index_id>/entry``
**Examples**
Delete an entry with a subject of ``https://example.com/foo/bar`` and
a null entry_id:
>>> sc = globus_sdk.SearchClient(...)
>>> sc.delete_entry(index_id, "https://example.com/foo/bar")
Delete an entry with a subject of ``https://example.com/foo/bar`` and
an entry_id of "foo/bar":
>>> sc = globus_sdk.SearchClient(...)
>>> sc.delete_entry(index_id, "https://example.com/foo/bar",
>>> entry_id="foo/bar")
**External Documentation**
See
`Delete Entry \
<https://docs.globus.org/api/search/entry_ops/#delete_single_entry>`_
in the API documentation for details.
"""
index_id = safe_stringify(index_id)
merge_params(params, subject=subject, entry_id=entry_id)
self.logger.info(
"SearchClient.delete_entry({}, {}, {}, ...)".format(
index_id, subject, entry_id
)
)
path = self.qjoin_path("v1/index", index_id, "entry")
return self.delete(path, params=params)
def oauth2_token_introspect(self, token, include=None):
"""
POST /v2/oauth2/token/introspect
Get information about a Globus Auth token.
>>> ac = globus_sdk.ConfidentialAppAuthClient(
... CLIENT_ID, CLIENT_SECRET)
>>> ac.oauth2_token_introspect('<token_string>')
**Parameters**
``token`` (*string*)
An Access Token as a raw string, being evaluated
``include`` (*string*)
A value for the ``include`` parameter in the request body. Default
is to omit the parameter, also supports ``"identity_set"``.
**External Documentation**
See
`Token Introspection \
<https://docs.globus.org/api/auth/reference/\
#token_introspection_post_v2_oauth2_token_introspect>`_
in the API documentation for details.
"""
self.logger.info('Checking token validity (introspect)')
body = {'token': token}
merge_params(body, include=include)
return self.post("/v2/oauth2/token/introspect", text_body=body)
def get_subject(self, index_id, subject, **params):
"""
``GET /v1/index/<index_id>/subject``
**Examples**
Fetch the data for subject ``http://example.com/abc`` from index
``index_id``:
>>> sc = globus_sdk.SearchClient(...)
>>> subject_data = sc.get_subject(index_id, 'http://example.com/abc')
**External Documentation**
See
`Get Subject \
<https://docs.globus.org/api/search/subject_ops/#get_by_subject>`_
in the API documentation for details.
"""
index_id = safe_stringify(index_id)
merge_params(params, subject=subject)
self.logger.info(f"SearchClient.get_subject({index_id}, {subject}, ...)")
path = self.qjoin_path("v1/index", index_id, "subject")
return self.get(path, params=params)
def delete_subject(self, index_id, subject, **params):
"""
``DELETE /v1/index/<index_id>/subject``
**Examples**
Delete all data for subject ``http://example.com/abc`` from index
``index_id``, even data which is not visible to the current user:
>>> sc = globus_sdk.SearchClient(...)
>>> subject_data = sc.get_subject(index_id, 'http://example.com/abc')
**External Documentation**
See
`Delete Subject \
<https://docs.globus.org/api/search/subject_ops/#delete_by_subject>`_
in the API documentation for details.
"""
index_id = safe_stringify(index_id)
merge_params(params, subject=subject)
self.logger.info(f"SearchClient.delete_subject({index_id}, {subject}, ...)")
path = self.qjoin_path("v1/index", index_id, "subject")
return self.delete(path, params=params)
def delete_entry(self, index_id, subject, entry_id=None, **params):
"""
``DELETE /v1/index/<index_id>/entry``
**Examples**
Delete an entry with a subject of ``https://example.com/foo/bar`` and
a null entry_id:
>>> sc = globus_sdk.SearchClient(...)
>>> sc.delete_entry(index_id, "https://example.com/foo/bar")
Delete an entry with a subject of ``https://example.com/foo/bar`` and
an entry_id of "foo/bar":
>>> sc = globus_sdk.SearchClient(...)
>>> sc.delete_entry(index_id, "https://example.com/foo/bar",
>>> entry_id="foo/bar")
**External Documentation**
See
`Delete Entry \
<https://docs.globus.org/api/search/entry_ops/#delete_single_entry>`_
in the API documentation for details.
"""
index_id = safe_stringify(index_id)
merge_params(params, subject=subject, entry_id=entry_id)
self.logger.info(
"SearchClient.delete_entry({}, {}, {}, ...)".format(
index_id, subject, entry_id
)
)
path = self.qjoin_path("v1/index", index_id, "entry")
return self.delete(path, params=params)
def get_subject(self, index_id, subject, **params):
"""
``GET /v1/index/<index_id>/subject``
**Examples**
Fetch the data for subject ``http://example.com/abc`` from index
``index_id``:
>>> sc = globus_sdk.SearchClient(...)
>>> subject_data = sc.get_subject(index_id, 'http://example.com/abc')
**External Documentation**
See
`Get Subject \
<https://docs.globus.org/api/search/subject_ops/#get_by_subject>`_
in the API documentation for details.
"""
index_id = safe_stringify(index_id)
merge_params(params, subject=subject)
self.logger.info(
"SearchClient.get_subject({}, {}, ...)".format(index_id, subject)
)
path = self.qjoin_path("v1/index", index_id, "subject")
return self.get(path, params=params)
def delete_subject(self, index_id, subject, **params):
"""
``DELETE /v1/index/<index_id>/subject``
**Examples**
Delete all data for subject ``http://example.com/abc`` from index
``index_id``, even data which is not visible to the current user:
>>> sc = globus_sdk.SearchClient(...)
>>> subject_data = sc.get_subject(index_id, 'http://example.com/abc')
**External Documentation**
See
`Delete Subject \
<https://docs.globus.org/api/search/subject_ops/#delete_by_subject>`_
in the API documentation for details.
"""
index_id = safe_stringify(index_id)
merge_params(params, subject=subject)
self.logger.info(
"SearchClient.delete_subject({}, {}, ...)".format(index_id, subject)
)
path = self.qjoin_path("v1/index", index_id, "subject")
return self.delete(path, params=params)
def token_introspect(self, token, **kw):
"""
Get information about a Globus Auth token. Requires basic auth
using oauth client credentials, where username=client_id
and password=client_secret.
"""
merge_params(kw, token=token)
return self.post("/v2/oauth2/token/introspect",
text_body=urllib.urlencode(kw)).json_body
def endpoint_search(self,
filter_fulltext=None,
filter_scope=None,
num_results=25,
**params):
r"""
.. parsed-literal::
GET /endpoint_search\
?filter_fulltext=<filter_fulltext>&filter_scope=<filter_scope>
:rtype: iterable of :class:`GlobusResponse
<globus_sdk.response.GlobusResponse>`
Search for a given string as a fulltext search:
>>> tc = globus_sdk.TransferClient()
>>> for ep in tc.endpoint_search('String to search for!'):
>>> print(ep['display_name'])
Search for a given string, but only on endpoints that you own:
>>> for ep in tc.endpoint_search('foo', filter_scope='my-endpoints'):
>>> print('{} has ID {}'.format(ep['display_name'], ep['id']))
Search results are capped at a number of elements equal to the
``num_results`` parameter.
If you want more than the default, 25, elements, do like so:
>>> for ep in tc.endpoint_search('String to search for!',
>>> num_results=120):
>>> print(ep['display_name'])
It is important to be aware that the Endpoint Search API limits
you to 1000 results for any search query.
If you attempt to exceed this limit, you will trigger a
:class:`PaginationOverrunError <globus_sdk.exc.PaginationOverrunError>`
>>> for ep in tc.endpoint_search('globus', # a very common string
>>> num_results=1200): # num too large!
>>> print(ep['display_name'])
will trigger this error.
For additional information, see `Endpoint Search
<https://docs.globus.org/api/transfer/endpoint_search>`_.
in the REST documentation for details.
"""
merge_params(params,
filter_scope=filter_scope,
filter_fulltext=filter_fulltext)
return PaginatedResource(self.get,
"endpoint_search", {'params': params},
num_results=num_results,
max_results_per_call=100,
max_total_results=1000)
def endpoint_search(self, filter_fulltext=None, filter_scope=None,
num_results=25, **params):
r"""
.. parsed-literal::
GET /endpoint_search\
?filter_fulltext=<filter_fulltext>&filter_scope=<filter_scope>
:rtype: iterable of :class:`GlobusResponse
<globus_sdk.response.GlobusResponse>`
Search for a given string as a fulltext search:
>>> tc = globus_sdk.TransferClient()
>>> for ep in tc.endpoint_search('String to search for!'):
>>> print(ep['display_name'])
Search for a given string, but only on endpoints that you own:
>>> for ep in tc.endpoint_search('foo', filter_scope='my-endpoints'):
>>> print('{} has ID {}'.format(ep['display_name'], ep['id']))
Search results are capped at a number of elements equal to the
``num_results`` parameter.
If you want more than the default, 25, elements, do like so:
>>> for ep in tc.endpoint_search('String to search for!',
>>> num_results=120):
>>> print(ep['display_name'])
It is important to be aware that the Endpoint Search API limits
you to 1000 results for any search query.
If you attempt to exceed this limit, you will trigger a
:class:`PaginationOverrunError <globus_sdk.exc.PaginationOverrunError>`
>>> for ep in tc.endpoint_search('globus', # a very common string
>>> num_results=1200): # num too large!
>>> print(ep['display_name'])
will trigger this error.
For additional information, see `Endpoint Search
<https://docs.globus.org/api/transfer/endpoint_search>`_.
in the REST documentation for details.
"""
merge_params(params, filter_scope=filter_scope,
filter_fulltext=filter_fulltext)
return PaginatedResource(
self.get, "endpoint_search", {'params': params},
num_results=num_results, max_results_per_call=100,
max_total_results=1000)
def test_merge_params():
"""
Merges a base parameter dict with other paramaters, validates results
Confirms works with explicit dictionaries and arguments
Confirms new parameters set to None are ignored
Confirms new parameters overwrite old ones (is this correct?)
"""
# explicit dictionary merging
params = {"param1": "value1"}
extra = {"param2": "value2", "param3": "value3"}
merge_params(params, **extra)
expected = {"param1": "value1", "param2": "value2", "param3": "value3"}
assert params == expected
# arguments
params = {"param1": "value1"}
merge_params(params, param2="value2", param3="value3")
expected = {"param1": "value1", "param2": "value2", "param3": "value3"}
assert params == expected
# ignoring parameters set to none
params = {"param1": "value1"}
merge_params(params, param2=None, param3=None)
expected = {"param1": "value1"}
assert params == expected
# existing parameters
params = {"param": "value"}
merge_params(params, param="newValue")
expected = {"param": "newValue"}
assert params == expected
def test_merge_params():
"""
Merges a base parameter dict with other paramaters, validates results
Confirms works with explicit dictionaries and arguments
Confirms new parameters set to None are ignored
Confirms new parameters overwrite old ones (is this correct?)
"""
# explicit dictionary merging
params = {"param1": "value1"}
extra = {"param2": "value2", "param3": "value3"}
merge_params(params, **extra)
expected = {"param1": "value1", "param2": "value2", "param3": "value3"}
assert params == expected
# arguments
params = {"param1": "value1"}
merge_params(params, param2="value2", param3="value3")
expected = {"param1": "value1", "param2": "value2", "param3": "value3"}
assert params == expected
# ignoring parameters set to none
params = {"param1": "value1"}
merge_params(params, param2=None, param3=None)
expected = {"param1": "value1"}
assert params == expected
# existing parameters
params = {"param": "value"}
merge_params(params, param="newValue")
expected = {"param": "newValue"}
assert params == expected
def search(self,
q,
limit=None,
offset=None,
query_template=None,
index=None,
advanced=None,
**params):
"""
Perform a simple ``GET`` based search.
Does not support all of the behaviors and parameters of advanced
searches.
**Parameters**
``q`` (*string*)
The user-query string. Required for simple searches (and most
advanced searches).
``index`` (*string*)
Optional unless ``default_index`` was not set.
The index to query.
``limit`` (*int*)
Optional. The number of results to return.
``offset`` (*int*)
Optional. An offset into the total result set for paging.
``query_template`` (*string*)
Optional. A query_template name as defined within the Search
service.
``advanced`` (*bool*)
Use simple query parsing vs. advanced query syntax when
interpreting ``q``. Defaults to False.
``params``
Any additional query params to pass. For internal use only.
"""
uri = slash_join(self._base_index_uri(index), 'search')
merge_params(params,
q=q,
limit=limit,
offset=offset,
query_template=query_template,
advanced=advanced)
return self.get(uri, params=params)
def get_group_tree(self, group_id, depth=None, my_roles=None,
my_statuses=None, **params):
# if not string, assume iterable
if my_roles and not isinstance(my_roles, six.string_types):
my_roles = ",".join(my_roles)
# if not string, assume iterable
if my_statuses and not isinstance(my_statuses, six.string_types):
my_statuses = ",".join(my_statuses)
merge_params(params, depth=depth, my_roles=my_roles,
my_statuses=my_statuses)
self.logger.debug("NexusClient.get_group_tree({},{})"
.format(group_id, str(params)))
return self.get('/groups/{}/tree'.format(group_id), params=params,
response_class=GlobusArrayResponse)
def token_introspect(self, token, **kw):
"""
POST /v2/oauth2/token/introspect
Get information about a Globus Auth token.
Requires Basic Auth using Oauth Client credentials.
See
`Token Introspection \
<https://docs.globus.org/api/auth/reference/\
#token_introspection_post_v2_oauth2_token_introspect>`_
in the API documentation for details.
"""
merge_params(kw, token=token)
return self.post("/v2/oauth2/token/introspect", text_body=urlencode(kw))
def token_introspect(self, token, **kw):
"""
POST /v2/oauth2/token/introspect
Get information about a Globus Auth token.
Requires Basic Auth using Oauth Client credentials.
See
`Token Introspection \
<https://docs.globus.org/api/auth/reference/\
#token_introspection_post_v2_oauth2_token_introspect>`_
in the API documentation for details.
"""
merge_params(kw, token=token)
return self.post("/v2/oauth2/token/introspect",
text_body=urlencode(kw))
def list_groups(self, for_all_identities=None,
fields=None, my_roles=None, **params):
"""
:rtype: GlobusResponse
"""
# if not string, assume iterable
if my_roles and not isinstance(my_roles, six.string_types):
my_roles = ",".join(my_roles)
# either string "true" (lowercase) or None (remove from params)
for_all_identities = 'true' if for_all_identities else None
merge_params(params, for_all_identities=for_all_identities,
fields=fields, my_roles=my_roles)
self.logger.debug("NexusClient.list_groups({})".format(str(params)))
return self.get('/groups', params=params,
response_class=GlobusArrayResponse)
def oauth2_token_introspect(self, token, include=None):
"""
POST /v2/oauth2/token/introspect
Get information about a Globus Auth token.
>>> ac = globus_sdk.ConfidentialAppAuthClient(
... CLIENT_ID, CLIENT_SECRET)
>>> ac.oauth2_token_introspect('<token_string>')
Get information about a Globus Auth token including the full identity
set of the user to whom it belongs
>>> ac = globus_sdk.ConfidentialAppAuthClient(
... CLIENT_ID, CLIENT_SECRET)
>>> data = ac.oauth2_token_introspect(
... '<token_string>', include='identity_set')
>>> for identity in data['identity_set']:
>>> print('token authenticates for "{}"'.format(identity))
**Parameters**
``token`` (*string*)
An Access Token as a raw string, being evaluated
``include`` (*string*)
A value for the ``include`` parameter in the request body. Default
is to omit the parameter, also supports ``"identity_set"``.
**External Documentation**
See
`Token Introspection \
<https://docs.globus.org/api/auth/reference/\
#token_introspection_post_v2_oauth2_token_introspect>`_
in the API documentation for details.
"""
self.logger.info("Checking token validity (introspect)")
body = {"token": token}
merge_params(body, include=include)
return self.post("/v2/oauth2/token/introspect", text_body=body)
def search(
self,
index_id,
q,
offset=0,
limit=10,
query_template=None,
advanced=False,
**params,
):
"""
``GET /v1/index/<index_id>/search``
**Examples**
>>> sc = globus_sdk.SearchClient(...)
>>> result = sc.search(index_id, 'query string')
>>> advanced_result = sc.search(index_id, 'author: "Ada Lovelace"',
>>> advanced=True)
**External Documentation**
See
`GET Search Query \
<https://docs.globus.org/api/search/search/#simple_get_query>`_
in the API documentation for details.
"""
index_id = safe_stringify(index_id)
merge_params(
params,
q=q,
offset=offset,
limit=limit,
query_template=query_template,
advanced=advanced,
)
self.logger.info(f"SearchClient.search({index_id}, ...)")
path = self.qjoin_path("v1/index", index_id, "search")
return self.get(path, params=params)
def search(
self,
index_id,
q,
offset=0,
limit=10,
query_template=None,
advanced=False,
**params
):
"""
``GET /v1/index/<index_id>/search``
**Examples**
>>> sc = globus_sdk.SearchClient(...)
>>> result = sc.search(index_id, 'query string')
>>> advanced_result = sc.search(index_id, 'author: "Ada Lovelace"',
>>> advanced=True)
**External Documentation**
See
`GET Search Query \
<https://docs.globus.org/api/search/search/#simple_get_query>`_
in the API documentation for details.
"""
index_id = safe_stringify(index_id)
merge_params(
params,
q=q,
offset=offset,
limit=limit,
query_template=query_template,
advanced=advanced,
)
self.logger.info("SearchClient.search({}, ...)".format(index_id))
path = self.qjoin_path("v1/index", index_id, "search")
return self.get(path, params=params)
def oauth2_token_introspect(self, token, include=None):
"""
POST /v2/oauth2/token/introspect
Get information about a Globus Auth token.
>>> ac = globus_sdk.ConfidentialAppAuthClient(
... CLIENT_ID, CLIENT_SECRET)
>>> ac.oauth2_token_introspect('<token_string>')
Get information about a Globus Auth token including the full identity
set of the user to whom it belongs
>>> ac = globus_sdk.ConfidentialAppAuthClient(
... CLIENT_ID, CLIENT_SECRET)
>>> data = ac.oauth2_token_introspect(
... '<token_string>', include='identity_set')
>>> for identity in data['identity_set']:
>>> print('token authenticates for "{}"'.format(identity))
:param token: An Access Token as a raw string, being evaluated
:type token: str
:param include: A value for the ``include`` parameter in the request body.
Default is to omit the parameter.
:type include: str, optional
**External Documentation**
See
`Token Introspection \
<https://docs.globus.org/api/auth/reference/\
#token_introspection_post_v2_oauth2_token_introspect>`_
in the API documentation for details.
"""
self.logger.info("Checking token validity (introspect)")
body = {"token": token}
merge_params(body, include=include)
return self.post("/v2/oauth2/token/introspect", text_body=body)
def get_entry(self, index_id, subject, entry_id=None, **params):
"""
``GET /v1/index/<index_id>/entry``
**Examples**
Lookup the entry with a subject of ``https://example.com/foo/bar`` and
a null entry_id:
>>> sc = globus_sdk.SearchClient(...)
>>> entry_data = sc.get_entry(index_id, 'http://example.com/foo/bar')
Lookup the entry with a subject of ``https://example.com/foo/bar`` and
an entry_id of ``foo/bar``:
>>> sc = globus_sdk.SearchClient(...)
>>> entry_data = sc.get_entry(index_id, 'http://example.com/foo/bar',
>>> entry_id='foo/bar')
**External Documentation**
See
`Get Entry \
<https://docs.globus.org/api/search/entry_ops/#get_single_entry>`_
in the API documentation for details.
"""
index_id = safe_stringify(index_id)
merge_params(params, subject=subject, entry_id=entry_id)
self.logger.info(
"SearchClient.get_entry({}, {}, {}, ...)".format(
index_id, subject, entry_id
)
)
path = self.qjoin_path("v1/index", index_id, "entry")
return self.get(path, params=params)
