def test_pop(self):
d = DotList([
{
'foo': 'bar'
},
{
'foo': 'baz'
},
])
item = d.pop()
self.assertEqual(item.foo, "baz")
def derived_bands(self,
bands=None,
require_bands=None,
limit=None,
offset=None,
**kwargs):
"""Search for predefined derived bands that you have access to.
:param list(str) bands: Limit the derived bands to ones that can be
computed using this list of spectral bands.
e.g ["red", "nir", "swir1"]
:param bool require_bands: Control whether searched bands must contain
all the spectral bands passed in the bands param.
Defaults to False.
:param int limit: Number of results to return.
:param int offset: Index to start at when returning results.
"""
params = ['bands', 'limit', 'offset']
args = locals()
kwargs = dict(
kwargs, **{
param: args[param]
for param in params if args[param] is not None
})
r = self.session.post('/bands/derived/search', json=kwargs)
return DotList(r.json())
def bands(self,
products=None,
limit=None,
offset=None,
wavelength=None,
resolution=None,
tags=None,
bands=None,
**kwargs):
"""Search for imagery data bands that you have access to.
:param list(str) products: A list of product(s) to return bands for.
:param int limit: Number of results to return.
:param int offset: Index to start at when returning results.
:param float wavelength: A wavelength in nm e.g 700 that the band sensor must measure.
:param int resolution: The resolution in meters per pixel e.g 30 of the data available in this band.
:param list(str) tags: A list of tags that the band must have in its own tag list.
"""
params = [
'limit', 'offset', 'products', 'wavelength', 'resolution', 'tags'
]
args = locals()
kwargs = dict(
kwargs, **{
param: args[param]
for param in params if args[param] is not None
})
r = self.session.post('/bands/search', json=kwargs)
return DotList(r.json())
def bands(self,
products=None,
limit=None,
offset=None,
wavelength=None,
resolution=None,
tags=None,
bands=None,
**kwargs):
"""Search for imagery data bands that you have access to.
:param list(str) products: A list of product(s) to return bands for.
:param int limit: Number of results to return.
:param int offset: Index to start at when returning results.
:param float wavelength: A wavelength in nm e.g 700 that the band sensor must measure.
:param int resolution: The resolution in meters per pixel e.g 30 of the data available in this band.
:param list(str) tags: A list of tags that the band must have in its own tag list.
:return: List of dicts containing at most `limit` bands. Empty if there are no
bands matching query (e.g. product id not available).
:rtype: DotList(DotDict)
"""
params = [
"limit", "offset", "products", "wavelength", "resolution", "tags"
]
args = locals()
kwargs = dict(
kwargs, **{
param: args[param]
for param in params if args[param] is not None
})
r = self.session.post("/bands/search", json=kwargs)
return DotList(r.json())
def products(self,
bands=None,
limit=None,
offset=None,
owner=None,
text=None,
**kwargs):
"""Search products that are available on the platform.
:param list(str) bands: Band name(s) e.g ["red", "nir"] to filter products by.
Note that products must match all bands that are passed.
:param int limit: Number of results to return.
:param int offset: Index to start at when returning results.
:param str owner: Filter products by the owner's uuid.
:param str text: Filter products by string match.
:return: List of dicts containing at most `limit` products. Empty if no matching
products are found.
:rtype: DotList(DotDict)
"""
params = ["limit", "offset", "bands", "owner", "text"]
args = locals()
kwargs = dict(
kwargs, **{
param: args[param]
for param in params if args[param] is not None
})
check_deprecated_kwargs(kwargs, {"band": "bands"})
r = self.session.post("/products/search", json=kwargs)
return DotList(r.json())
def rerun_tasks(self, group_id, task_id_iterable, retry_count=0):
"""
Submits a list of completed tasks specified by ids for a rerun. The completed tasks
with the given ids will be run again with the same arguments as before.
Tasks that are currently already being rerun will be ignored. Unknown or invalid
task ids will be ignored.
:param str group_id: The group in which to rerun tasks.
:param iterable(str) task_id_iterable: An iterable of the task ids to be rerun.
:param int retry_count: Number of times to retry a task if it fails
(maximum 5)
:return: A list of dictionaries representing the tasks that have been submitted.
"""
rerun = []
task_ids = list(
itertools.islice(task_id_iterable, self.RERUN_BATCH_SIZE))
while task_ids:
r = self.session.post(
"/groups/{group_id}/tasks/rerun".format(group_id=group_id),
json={
'task_ids': task_ids,
'retry_count': retry_count,
})
r.raise_for_status()
rerun += r.json()['tasks']
task_ids = list(
itertools.islice(task_id_iterable, self.RERUN_BATCH_SIZE))
return DotList(rerun)
def products(self,
bands=None,
limit=None,
offset=None,
owner=None,
text=None,
**kwargs):
"""Search products that are available on the platform.
:param list(str) bands: Band name(s) e.g ["red", "nir"] to filter products by.
Note that products must match all bands that are passed.
:param int limit: Number of results to return.
:param int offset: Index to start at when returning results.
:param str owner: Filter products by the owner's uuid.
:param str text: Filter products by string match.
"""
params = ['limit', 'offset', 'bands', 'owner', 'text']
args = locals()
kwargs = dict(
kwargs, **{
param: args[param]
for param in params if args[param] is not None
})
r = self.session.post('/products/search', json=kwargs)
return DotList(r.json())
def get_by_ids(self, ids):
"""Get metadata for multiple images by id. The response contains found images in the
order of the given ids. If no image exists for an id, that id is ignored.
:param list(str) ids: Image identifiers.
:return: List of image metadata.
"""
r = self.session.post('/batch/images', json={'ids': ids})
return DotList(r.json())
def test_slice(self):
d = DotList([
[1, 2],
{
'foo': 'bar'
},
])
sliced = d[0:2]
self.assertIsInstance(sliced, DotList)
self.assertEqual(2, len(sliced))
def test_basic(self):
d = DotDict({"a": 1, "b": 2})
unboxed = d.asdict()
assert type(unboxed) == dict
assert unboxed == d
obj = DotDict(a=d)
unboxed = obj.asdict()
assert type(unboxed["a"]) == dict
obj = DotList(DotDict(i=i) for i in range(10))
unboxed = obj.aslist()
assert type(unboxed) == list
assert all(type(x) is dict for x in unboxed)
obj = DotDict({i: DotList(range(i)) for i in range(10)})
unboxed = obj.asdict()
assert all(type(x) is list for x in six.itervalues(unboxed))
def test_basic(self):
d = DotDict({"a": 1, "b": 2})
unboxed = d.asdict()
self.assertEqual(type(unboxed), dict)
self.assertEqual(unboxed, d)
obj = DotDict(a=d)
unboxed = obj.asdict()
self.assertEqual(type(unboxed["a"]), dict)
obj = DotList(DotDict(i=i) for i in range(10))
unboxed = obj.aslist()
self.assertEqual(type(unboxed), list)
self.assertTrue(all(type(x) is dict for x in unboxed))
obj = DotDict({i: DotList(range(i)) for i in range(10)})
unboxed = obj.asdict()
self.assertTrue(all(type(x) is list for x in six.itervalues(unboxed)))
def test_iterate(self):
d = DotList([
{
'foo': 'bar'
},
{
'foo': 'baz'
},
])
foos = [foo.foo for foo in d]
self.assertEqual(['bar', 'baz'], foos)
def random_container(cls, height=6):
make_dict = random.choice((True, False, None))
if height == 0 or make_dict is None:
return random.randint(0, 100)
if make_dict:
return DotDict({
i: cls.random_container(height - 1)
for i in range(random.randint(1, 5))
})
else:
return DotList(
cls.random_container(height - 1)
for i in range(random.randint(1, 5)))
def available_products(self):
"""Get the list of product identifiers you have access to.
Example::
>>> from descarteslabs.client.services import Metadata
>>> products = Metadata().available_products()
>>> products # doctest: +SKIP
['landsat:LC08:PRE:TOAR']
"""
r = self.session.get('/products')
return DotList(r.json())
def ids(self, products=None, sat_id=None, date='acquired', place=None,
geom=None, start_datetime=None, end_datetime=None, cloud_fraction=None,
cloud_fraction_0=None, fill_fraction=None, q=None, limit=100, offset=None,
dltile=None, sort_field=None, sort_order=None, randomize=None, **kwargs):
"""Search metadata given a spatio-temporal query. All parameters are
optional.
:param list(str) products: Products identifier(s).
:param list(str) sat_id: Satellite identifier(s).
:param str date: The date field to use for search (e.g. `acquired`).
:param str place: A slug identifier to be used as a region of interest.
:param str geom: A GeoJSON or WKT region of interest.
:param str start_datetime: Desired starting timestamp, in any common format.
:param str end_datetime: Desired ending timestamp, in any common format.
:param float cloud_fraction: Maximum cloud fraction, calculated by data provider.
:param float cloud_fraction_0: Maximum cloud fraction, calculated by cloud mask pixels.
:param float fill_fraction: Minimum scene fill fraction, calculated as valid/total pixels.
:param expr q: Expression for filtering the results. See :py:attr:`descarteslabs.utilities.properties`.
:param int limit: Number of items to return.
:param int offset: Number of items to skip.
:param str dltile: a dltile key used to specify the resolution, bounds, and srs.
:param str sort_field: Property to sort on.
:param str sort_order: Order of sort.
:param bool randomize: Randomize the results. You may also use an `int` or `str` as an explicit seed.
:return: List of image identifiers.
Example::
>>> from descarteslabs.client.services import Metadata
>>> ids = Metadata().ids(place='north-america_united-states_iowa', \
products=['landsat:LC08:PRE:TOAR'], \
start_datetime='2016-07-01', \
end_datetime='2016-07-31T23:59:59')
>>> len(ids) # doctest: +SKIP
1
>>> ids # doctest: +SKIP
['landsat:LC08:PRE:TOAR:meta_LC80260322016197_v1', 'landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1']
"""
result = self.search(sat_id=sat_id, products=products, date=date,
place=place, geom=geom, start_datetime=start_datetime,
end_datetime=end_datetime, cloud_fraction=cloud_fraction,
cloud_fraction_0=cloud_fraction_0, fill_fraction=fill_fraction,
q=q, limit=limit, offset=offset, fields=[], dltile=dltile,
sort_field=sort_field, sort_order=sort_order, randomize=randomize, **kwargs)
return DotList(feature['id'] for feature in result['features'])
def search(self, q, limit=10, country=None, region=None, placetype=None):
"""Search for shapes
:param str q: A query string.
:param int limit: Max number of matches to return
:param str country: Restrict search to a specific country
:param str region: Restrict search to a specific region
:param str placetype: Restrict search to a specific placetype
:return: list of candidates
Example::
>>> from descarteslabs.client.services import Places
>>> results = Places().search('texas')
>>> results[0]
{
'bbox': [-106.645584, 25.837395, -93.508039, 36.50035],
'id': 85688753,
'name': 'Texas',
'placetype': 'region',
'slug': 'north-america_united-states_texas'
}
"""
params = {}
if q:
params['q'] = q
if country:
params['country'] = country
if region:
params['region'] = region
if placetype:
params['placetype'] = placetype
if limit:
params['n'] = limit
r = self.session.get('/search', params=params, timeout=self.TIMEOUT)
return DotList(r.json())
def get_by_ids(self, ids, fields=None, ignore_not_found=True, **kwargs):
"""Get metadata for multiple images by id. The response contains found images in the
order of the given ids.
:param list(str) ids: Image identifiers.
:param list(str) fields: Properties to return.
:param bool ignore_not_found: For image id lookups that fail: if :py:obj:`True`, ignore;
if :py:obj:`False`, raise :py:exc:`NotFoundError`. Default is :py:obj:`True`.
:return: List of image metadata.
:rtype: list(dict)
"""
kwargs["ids"] = ids
kwargs["ignore_not_found"] = ignore_not_found
if fields is not None:
kwargs["fields"] = fields
r = self.session.post("/batch/images", json=kwargs)
return DotList(r.json())
def find(self, path, **kwargs):
"""Find candidate slugs based on full or partial path.
:param str path: Candidate underscore-separated slug.
:param placetype: Optional place type for filtering.
Example::
>>> from descarteslabs.client.services import Places
>>> results = Places().find('morocco')
>>> _ = results[0].pop('bbox')
>>> results
[
{
'id': 85632693,
'name': 'Morocco',
'path': 'continent:africa_country:morocco',
'placetype': 'country',
'slug': 'africa_morocco'
}
]
"""
r = self.session.get('/find/%s' % path, params=kwargs)
return DotList(r.json())
def test_pop(self):
d = DotList([{"foo": "bar"}, {"foo": "baz"}])
item = d.pop()
assert item.foo == "baz"
def test_iterate(self):
d = DotList([{"foo": "bar"}, {"foo": "baz"}])
foos = [foo.foo for foo in d]
assert ["bar", "baz"] == foos
def test_slice(self):
d = DotList([[1, 2], {"foo": "bar"}])
sliced = d[0:2]
assert isinstance(sliced, DotList)
assert 2 == len(sliced)
def test_from_list(self):
template = list(range(10))
dotlist = DotList(template)
assert dotlist == template
assert isinstance(dotlist, DotList)
assert isinstance(dotlist, list)
def test_iterate(self):
d = DotList([{"foo": "bar"}, {"foo": "baz"}])
foos = [foo.foo for foo in d]
self.assertEqual(["bar", "baz"], foos)
def test_pop(self):
d = DotList([{"foo": "bar"}, {"foo": "baz"}])
item = d.pop()
self.assertEqual(item.foo, "baz")
def metrics(self):
"""Get a list of metrics
"""
r = self.session.get('/metrics', timeout=self.TIMEOUT)
return DotList(r.json())
def categories(self):
"""Get a list of categories
"""
r = self.session.get('/categories', timeout=self.TIMEOUT)
return DotList(r.json())
def sources(self):
"""Get a list of sources
"""
r = self.session.get('/sources', timeout=self.TIMEOUT)
return DotList(r.json())
def search(self,
products=None,
sat_ids=None,
date="acquired",
place=None,
geom=None,
start_datetime=None,
end_datetime=None,
cloud_fraction=None,
cloud_fraction_0=None,
fill_fraction=None,
q=None,
limit=100,
fields=None,
dltile=None,
sort_field=None,
sort_order="asc",
randomize=None,
**kwargs):
"""Search metadata given a spatio-temporal query. All parameters are
optional.
If performing a large query, consider using the iterator :py:func:`features` instead.
:param list(str) products: Product Identifier(s).
:param list(str) sat_ids: Satellite identifier(s).
:param str date: The date field to use for search (e.g. `acquired`).
:param str place: A slug identifier to be used as a region of interest.
:param str geom: A GeoJSON or WKT region of interest.
:param str start_datetime: Desired starting timestamp, in any common format.
:param str end_datetime: Desired ending timestamp, in any common format.
:param float cloud_fraction: Maximum cloud fraction, calculated by data provider.
:param float cloud_fraction_0: Maximum cloud fraction, calculated by cloud mask pixels.
:param float fill_fraction: Minimum scene fill fraction, calculated as valid/total pixels.
:param expr q: Expression for filtering the results. See
:py:attr:`descarteslabs.client.services.metadata.properties`.
:param int limit: Maximum number of items to return.
:param list(str) fields: Properties to return.
:param str dltile: a dltile key used to specify the resolution, bounds, and srs.
:param str sort_field: Property to sort on.
:param str sort_order: Order of sort.
:param bool randomize: Randomize the results. You may also use an `int` or `str` as an explicit seed.
return: GeoJSON ``FeatureCollection``
Note that as of release 0.16.0 the ``continuation_token`` token has been removed. Please use the
:py:func:`paged_search` if you require this feature.
Example::
>>> from descarteslabs.client.services import Metadata
>>> iowa_geom = {
... "coordinates": [[
... [-96.498997, 42.560832],
... [-95.765645, 40.585208],
... [-91.729115, 40.61364],
... [-91.391613, 40.384038],
... [-90.952233, 40.954047],
... [-91.04589, 41.414085],
... [-90.343228, 41.587833],
... [-90.140613, 41.995999],
... [-91.065059, 42.751338],
... [-91.217706, 43.50055],
... [-96.599191, 43.500456],
... [-96.498997, 42.560832]
... ]],
... "type": "Polygon"
... }
>>> scenes = Metadata().search(
... geom=iowa_geom,
... products=['landsat:LC08:PRE:TOAR'],
... start_datetime='2016-07-01',
... end_datetime='2016-07-31T23:59:59'
... )
>>> len(scenes['features']) # doctest: +SKIP
2
"""
features_iter = self.features(products=products,
sat_ids=sat_ids,
date=date,
place=place,
geom=geom,
start_datetime=start_datetime,
end_datetime=end_datetime,
cloud_fraction=cloud_fraction,
cloud_fraction_0=cloud_fraction_0,
fill_fraction=fill_fraction,
q=q,
fields=fields,
dltile=dltile,
sort_field=sort_field,
sort_order=sort_order,
randomize=randomize,
**kwargs)
limited_features = itertools.islice(features_iter, limit)
return DotDict(type="FeatureCollection",
features=DotList(limited_features))
def sources(self):
warn(SOURCES_DEPRECATION_MESSAGE, DeprecationWarning)
r = self.session.get('/sources')
return DotList(r.json())
def ids(self,
products=None,
sat_ids=None,
date="acquired",
place=None,
geom=None,
start_datetime=None,
end_datetime=None,
cloud_fraction=None,
cloud_fraction_0=None,
fill_fraction=None,
q=None,
limit=100,
dltile=None,
sort_field=None,
sort_order=None,
randomize=None,
**kwargs):
"""Search metadata given a spatio-temporal query. All parameters are
optional.
:param list(str) products: Products identifier(s).
:param list(str) sat_ids: Satellite identifier(s).
:param str date: The date field to use for search (e.g. `acquired`).
:param str place: A slug identifier to be used as a region of interest.
:param str geom: A GeoJSON or WKT region of interest.
:param str start_datetime: Desired starting timestamp, in any common format.
:param str end_datetime: Desired ending timestamp, in any common format.
:param float cloud_fraction: Maximum cloud fraction, calculated by data provider.
:param float cloud_fraction_0: Maximum cloud fraction, calculated by cloud mask pixels.
:param float fill_fraction: Minimum scene fill fraction, calculated as valid/total pixels.
:param expr q: Expression for filtering the results. See
:py:attr:`descarteslabs.client.services.metadata.properties`.
:param int limit: Number of items to return.
:param str dltile: a dltile key used to specify the resolution, bounds, and srs.
:param str sort_field: Property to sort on.
:param str sort_order: Order of sort.
:param bool randomize: Randomize the results. You may also use an `int` or `str` as an explicit seed.
:return: List of image identifiers.
Example::
>>> from descarteslabs.client.services import Metadata
>>> iowa_geom = {
... "coordinates": [[
... [-96.498997, 42.560832],
... [-95.765645, 40.585208],
... [-91.729115, 40.61364],
... [-91.391613, 40.384038],
... [-90.952233, 40.954047],
... [-91.04589, 41.414085],
... [-90.343228, 41.587833],
... [-90.140613, 41.995999],
... [-91.065059, 42.751338],
... [-91.217706, 43.50055],
... [-96.599191, 43.500456],
... [-96.498997, 42.560832]
... ]],
... "type": "Polygon"
... }
>>> ids = Metadata().ids(geom=iowa_geom,
... products=['landsat:LC08:PRE:TOAR'],
... start_datetime='2016-07-01',
... end_datetime='2016-07-31T23:59:59')
>>> len(ids) # doctest: +SKIP
2
>>> ids # doctest: +SKIP
['landsat:LC08:PRE:TOAR:meta_LC80260322016197_v1', 'landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1']
"""
result = self.search(sat_ids=sat_ids,
products=products,
date=date,
place=place,
geom=geom,
start_datetime=start_datetime,
end_datetime=end_datetime,
cloud_fraction=cloud_fraction,
cloud_fraction_0=cloud_fraction_0,
fill_fraction=fill_fraction,
q=q,
limit=limit,
fields=[],
dltile=dltile,
sort_field=sort_field,
sort_order=sort_order,
randomize=randomize,
**kwargs)
return DotList(feature["id"] for feature in result["features"])
