dep_tools.searchers module

This module contains the definition and implementation of Searcher objects.

class dep_tools.searchers.Searcher[source]

Bases: ABC

An object which searches for something, based on an area.

abstract search(area)[source]

class dep_tools.searchers.PystacSearcher(catalog=None, client=None, raise_empty_collection_error=True, **kwargs)[source]

Bases: Searcher

A Searcher which searches for stac items using pystac_client.Client.search.

Fixes include correctly searching across the antimeridian by splitting the bounding box of the target area on either side and removal of known “bad” stac items (using dep_tools.utils.remove_bad_items).

This is written to be used with the Task framework. If you just want to search for stac items and handle the antimeridian correctly, use dep_tools.utils.search_across_180().

Parameters:

catalog (Optional[str]) – The URL of a stac catalog. if client is specified, this is ignored.
client (Optional[Client]) – A search client. Either this or catalog must be specified.
raise_empty_collection_error (bool) – Whether an EmptyCollectionError exception should be returned if no stac items are found.
**kwargs – Additional arguments passed to client.search(). For example, passing collections=[“sentinel-2-l2a”] will restrict results to Sentinel 2 stac items.

search(area)[source]

Search for stac items within the bounds of the corresponding area.

Parameters:: area (GeoDataFrame | GeoBox) – An area in any projection as defined by the crs.
Return type:: ItemCollection
Returns:: An ItemCollection.

class dep_tools.searchers.LandsatPystacSearcher(catalog=None, client=None, collections=['landsat-c2-l2'], raise_empty_collection_error=True, search_intersecting_pathrows=False, exclude_platforms=None, only_tier_one=False, fall_back_to_tier_two=False, **kwargs)[source]

Bases: PystacSearcher

A PystacSearcher with special functionality for landsat data on the MSPC. Currently it overwrites any query kwarg, so if you want a direct query, just use :class:PystacSearcher.

Parameters:

catalog (Optional[str]) – The URL of a stac catalog. if client is specified, this is ignored.
client (Optional[Client]) – A search client. Either this or catalog must be specified.
raise_empty_collection_error (bool) – Whether an EmptyCollectionError exception should be returned if no stac items are found.
search_intersecting_pathrows (bool) – Whether to use landsat pathrows which intersect the area passed to :func:search rather than the area itself. This is a workaround for bad geometry in some stac items which cross the antimeridian.
exclude_platforms (Optional[list[str]]) – A list of platforms (e.g. [“landsat-7”]) to exclude from searching.
only_tier_one (bool) – Whether to only search for tier one landsat data.
fall_back_to_tier_two (bool) – If only_tier_one is set to True and no items are returned from the search, search again with tier two data included.
**kwargs – Additional arguments passed to client.search(). collections and query arguments will be overwritten.

search(area)[source]

Perform the search.

Parameters:: area (GeoDataFrame) – Any area.
Returns:: An ItemCollection.
Raises:: EmptyCollectionError – If the search finds no items.