def read_dict(
d: Dict[str, Any],
href: Optional[str] = None,
root: Optional[Catalog] = None,
stac_io: Optional[StacIO] = None,
) -> STACObject:
"""Reads a :class:`~STACObject` or :class:`~ItemCollection` from a JSON-like dict
representing a serialized STAC object.
This method will return either a :class:`~Catalog`, :class:`~Collection`,
or :class`~Item` based on the contents of the dict.
This is a convenience method for either
:meth:`StacIO.stac_object_from_dict <pystac.StacIO.stac_object_from_dict>`.
Args:
d : The dict to parse.
href : Optional href that is the file location of the object being
parsed.
root : Optional root of the catalog for this object.
If provided, the root's resolved object cache can be used to search for
previously resolved instances of the STAC object.
stac_io: Optional :class:`~StacIO` instance to use for reading. If ``None``,
the default instance will be used.
Raises:
STACTypeError : If the ``d`` dictionary does not represent a valid
:class:`~pystac.STACObject`. Note that an :class:`~pystac.ItemCollection`
is not a :class:`~pystac.STACObject` and must be read using
:meth:`ItemCollection.from_dict <pystac.ItemCollection.from_dict>`
"""
if stac_io is None:
stac_io = StacIO.default()
return stac_io.stac_object_from_dict(d, href, root)
def read_file(href: HREF, stac_io: Optional[StacIO] = None) -> STACObject:
"""Reads a STAC object from a file.
This method will return either a Catalog, a Collection, or an Item based on what
the file contains.
This is a convenience method for :meth:`StacIO.read_stac_object
<pystac.StacIO.read_stac_object>`
Args:
href : The HREF to read the object from.
stac_io: Optional :class:`~StacIO` instance to use for I/O operations. If not
provided, will use :meth:`StacIO.default` to create an instance.
Returns:
The specific STACObject implementation class that is represented
by the JSON read from the file located at HREF.
Raises:
STACTypeError : If the file at ``href`` does not represent a valid
:class:`~pystac.STACObject`. Note that an :class:`~pystac.ItemCollection`
is not a :class:`~pystac.STACObject` and must be read using
:meth:`ItemCollection.from_file <pystac.ItemCollection.from_file>`
"""
if stac_io is None:
stac_io = StacIO.default()
return stac_io.read_stac_object(href)
def write_file(
obj: STACObject,
include_self_link: bool = True,
dest_href: Optional[HREF] = None,
stac_io: Optional[StacIO] = None,
) -> None:
"""Writes a STACObject to a file.
This will write only the Catalog, Collection or Item ``obj``. It will not attempt
to write any other objects that are linked to ``obj``; if you'd like functionality
to save off catalogs recursively see :meth:`Catalog.save <pystac.Catalog.save>`.
This method will write the JSON of the object to the object's assigned "self" link
or to the dest_href if provided. To set the self link, see
:meth:`STACObject.set_self_href <pystac.STACObject.set_self_href>`.
Convenience method for :meth:`STACObject.from_file <pystac.STACObject.from_file>`
Args:
obj : The STACObject to save.
include_self_link : If ``True``, include the ``"self"`` link with this object.
Otherwise, leave out the self link.
dest_href : Optional HREF to save the file to. If ``None``, the object will be
saved to the object's ``"self"`` href.
stac_io: Optional :class:`~StacIO` instance to use for I/O operations. If not
provided, will use :meth:`StacIO.default` to create an instance.
"""
if stac_io is None:
stac_io = StacIO.default()
dest_href = None if dest_href is None else str(os.fspath(dest_href))
obj.save_object(include_self_link=include_self_link,
dest_href=dest_href,
stac_io=stac_io)
'/vsitar/vsigzip/') and not uri.startswith('/vsitar/vsigzip//'):
uri = uri.replace('/vsitar/vsigzip/', '/vsitar/vsigzip//')
return uri
return VsiFileSystem.read_str(uri)
class CustomStacIO(DefaultStacIO):
def read_text(self, source, *args, **kwargs) -> str:
return VsiFileSystem.read_str(pystac_workaround(source))
def write_text(self, dest, txt, *args, **kwargs) -> None:
pass
StacIO.set_default(CustomStacIO)
def root_of_tarball(tarball: str) -> str:
catalog_root = pystac_workaround(tarball)
while not (catalog_root.endswith('catalog.json')
and catalog_root is not None):
paths = VsiFileSystem.list_paths(catalog_root)
if len(paths) > 1:
paths = list(filter(lambda s: s.endswith('catalog.json'), paths))
if len(paths) != 1:
raise Exception('Unrecognizable Tarball')
catalog_root = f'{paths[0]}'
return catalog_root
def use_fsspec():
StacIO.set_default(FsspecStacIO)
def read_text(href: str,
read_href_modifier: Optional[ReadHrefModifier] = None) -> str:
if read_href_modifier is None:
return StacIO.default().read_text(href)
else:
return StacIO.default().read_text(read_href_modifier(href))
def setUp(self) -> None:
self.stac_io = StacIO.default()
def use_fsspec() -> None:
StacIO.set_default(FsspecStacIO)