Source code for grass.temporal.list_stds

"""
Functions to create space time dataset lists

Usage:

.. code-block:: python

    import grass.temporal as tgis

    tgis.register_maps_in_space_time_dataset(type, name, maps)


(C) 2012-2022 by the GRASS Development Team
This program is free software under the GNU General Public
License (>=v2). Read the file COPYING that comes with GRASS GIS
for details.

:authors: Soeren Gebbert
:authors: Vaclav Petras
"""

import os
from contextlib import contextmanager
import sys

import grass.script as gs

from .core import get_tgis_message_interface, get_available_temporal_mapsets, init_dbif
from .datetime_math import time_delta_to_relative_time
from .factory import dataset_factory
from .open_stds import open_old_stds

###############################################################################


[docs]def get_dataset_list( type, temporal_type, columns=None, where=None, order=None, dbif=None ): """Return a list of time stamped maps or space time datasets of a specific temporal type that are registered in the temporal database This method returns a dictionary, the keys are the available mapsets, the values are the rows from the SQL database query. :param type: The type of the datasets (strds, str3ds, stvds, raster, raster_3d, vector) :param temporal_type: The temporal type of the datasets (absolute, relative) :param columns: A comma separated list of columns that will be selected :param where: A where statement for selected listing without "WHERE" :param order: A comma separated list of columns to order the datasets by category :param dbif: The database interface to be used :return: A dictionary with the rows of the SQL query for each available mapset .. code-block:: python >>> import grass.temporal as tgis >>> tgis.core.init() >>> name = "list_stds_test" >>> sp = tgis.open_stds.open_new_stds( ... name=name, ... type="strds", ... temporaltype="absolute", ... title="title", ... descr="descr", ... semantic="mean", ... dbif=None, ... overwrite=True, ... ) >>> mapset = tgis.get_current_mapset() >>> stds_list = tgis.list_stds.get_dataset_list( ... "strds", "absolute", columns="name" ... ) >>> rows = stds_list[mapset] >>> for row in rows: ... if row["name"] == name: ... print(True) ... True >>> stds_list = tgis.list_stds.get_dataset_list( ... "strds", ... "absolute", ... columns="name,mapset", ... where="mapset = '%s'" % (mapset), ... ) >>> rows = stds_list[mapset] >>> for row in rows: ... if row["name"] == name and row["mapset"] == mapset: ... print(True) ... True >>> check = sp.delete() """ id = None sp = dataset_factory(type, id) dbif, connection_state_changed = init_dbif(dbif) mapsets = get_available_temporal_mapsets() result = {} for mapset in mapsets.keys(): if temporal_type == "absolute": table = sp.get_type() + "_view_abs_time" else: table = sp.get_type() + "_view_rel_time" if columns and columns.find("all") == -1: sql = "SELECT " + str(columns) + " FROM " + table else: sql = "SELECT * FROM " + table if where: sql += " WHERE " + where sql += " AND mapset = '%s'" % (mapset) else: sql += " WHERE mapset = '%s'" % (mapset) if order: sql += " ORDER BY " + order dbif.execute(sql, mapset=mapset) rows = dbif.fetchall(mapset=mapset) if rows: result[mapset] = rows if connection_state_changed: dbif.close() return result
############################################################################### @contextmanager def _open_output_file(file, encoding="utf-8", **kwargs): if not file: yield sys.stdout elif not isinstance(file, (str, os.PathLike)): yield file else: with open(file, "w", encoding=encoding, **kwargs) as stream: yield stream def _write_line(items, separator, file): if not separator: separator = "," output = separator.join([f"{item}" for item in items]) with _open_output_file(file) as stream: print(f"{output}", file=stream) def _write_plain(rows, header, separator, file): def write_plain_row(items, separator, file): output = separator.join([f"{item}" for item in items]) print(f"{output}", file=file) with _open_output_file(file) as stream: # Print the column names if requested if header: write_plain_row(items=header, separator=separator, file=stream) for row in rows: write_plain_row(items=row, separator=separator, file=stream) def _write_json(rows, column_names, file): # Lazy import output format-specific dependencies. # pylint: disable=import-outside-toplevel import json import datetime class ResultsEncoder(json.JSONEncoder): """Results encoder for JSON which handles SimpleNamespace objects""" def default(self, o): """Handle additional types""" if isinstance(o, datetime.datetime): return f"{o}" return super().default(o) dict_rows = [] for row in rows: new_row = {} for key, value in zip(column_names, row): new_row[key] = value dict_rows.append(new_row) meta = {"column_names": column_names} with _open_output_file(file) as stream: json.dump({"data": dict_rows, "metadata": meta}, stream, cls=ResultsEncoder) def _write_yaml(rows, column_names, file=sys.stdout): # Lazy import output format-specific dependencies. # pylint: disable=import-outside-toplevel import yaml class NoAliasIndentListSafeDumper(yaml.SafeDumper): """YAML dumper class which does not create aliases and indents lists This avoid dates being labeled with &id001 and referenced with *id001. Instead, same dates are simply repeated. Lists have their dash-space (- ) indented instead of considering the dash and space to be a part of indentation. This might be better handled when https://github.com/yaml/pyyaml/issues/234 is resolved. """ def ignore_aliases(self, data): return True def increase_indent(self, flow=False, indentless=False): return super().increase_indent(flow=flow, indentless=False) dict_rows = [] for row in rows: new_row = {} for key, value in zip(column_names, row): new_row[key] = value dict_rows.append(new_row) meta = {"column_names": column_names} with _open_output_file(file) as stream: print( yaml.dump( {"data": dict_rows, "metadata": meta}, Dumper=NoAliasIndentListSafeDumper, default_flow_style=False, ), end="", file=stream, ) def _write_csv(rows, column_names, separator, file=sys.stdout): # Lazy import output format-specific dependencies. # pylint: disable=import-outside-toplevel import csv # Newlines handled by the CSV writer. Set according to the package doc. with _open_output_file(file, newline="") as stream: spamwriter = csv.writer( stream, delimiter=separator, quotechar='"', doublequote=True, quoting=csv.QUOTE_NONNUMERIC, lineterminator="\n", ) if column_names: spamwriter.writerow(column_names) for row in rows: spamwriter.writerow(row) def _write_table(rows, column_names, output_format, separator, file): if output_format == "json": _write_json(rows=rows, column_names=column_names, file=file) elif output_format == "yaml": _write_yaml(rows=rows, column_names=column_names, file=file) elif output_format == "plain": # No particular reason for this separator except that this is the original # behavior. if not separator: separator = "\t" _write_plain(rows=rows, header=column_names, separator=separator, file=file) elif output_format == "csv": if not separator: separator = "," _write_csv(rows=rows, column_names=column_names, separator=separator, file=file) else: raise ValueError(f"Unknown value '{output_format}' for output_format") def _get_get_registered_maps_as_objects_with_method(dataset, where, method, gran, dbif): if method == "deltagaps": return dataset.get_registered_maps_as_objects_with_gaps(where=where, dbif=dbif) if method == "delta": return dataset.get_registered_maps_as_objects( where=where, order="start_time", dbif=dbif ) if method == "gran": if where: raise ValueError( f"The where parameter is not supported with method={method}" ) if gran is not None and gran != "": return dataset.get_registered_maps_as_objects_by_granularity( gran=gran, dbif=dbif ) return dataset.get_registered_maps_as_objects_by_granularity(dbif=dbif) raise ValueError(f"Invalid method '{method}'") def _get_get_registered_maps_as_objects_delta_gran( dataset, where, method, gran, dbif, msgr ): maps = _get_get_registered_maps_as_objects_with_method( dataset=dataset, where=where, method=method, gran=gran, dbif=dbif ) if not maps: return [] if isinstance(maps[0], list): if len(maps[0]) > 0: first_time, unused = maps[0][0].get_temporal_extent_as_tuple() else: msgr.warning(_("Empty map list")) return [] else: first_time, unused = maps[0].get_temporal_extent_as_tuple() records = [] for map_object in maps: if isinstance(map_object, list): if len(map_object) > 0: map_object = map_object[0] else: msgr.fatal(_("Empty entry in map list, this should not happen")) start, end = map_object.get_temporal_extent_as_tuple() if end: delta = end - start else: delta = None delta_first = start - first_time if map_object.is_time_absolute(): if end: delta = time_delta_to_relative_time(delta) delta_first = time_delta_to_relative_time(delta_first) records.append((map_object, start, end, delta, delta_first)) return records def _get_list_of_maps_delta_gran(dataset, columns, where, method, gran, dbif, msgr): maps = _get_get_registered_maps_as_objects_delta_gran( dataset=dataset, where=where, method=method, gran=gran, dbif=dbif, msgr=msgr ) rows = [] for map_object, start, end, delta, delta_first in maps: row = [] # Here the names must be the same as in the database # to make the interface consistent. for column in columns: if column == "id": row.append(map_object.get_id()) elif column == "name": row.append(map_object.get_name()) elif column == "layer": row.append(map_object.get_layer()) elif column == "mapset": row.append(map_object.get_mapset()) elif column == "start_time": row.append(start) elif column == "end_time": row.append(end) elif column == "interval_length": row.append(delta) elif column == "distance_from_begin": row.append(delta_first) else: raise ValueError(f"Unsupported column '{column}'") rows.append(row) return rows def _get_list_of_maps_stds( element_type, name, columns, order, where, method, output_format, gran=None, dbif=None, ): dbif, connection_state_changed = init_dbif(dbif) msgr = get_tgis_message_interface() dataset = open_old_stds(name, element_type, dbif) def check_columns(column_names, output_format, element_type): if element_type != "stvds" and "layer" in columns: raise ValueError( f"Column 'layer' is not allowed with temporal type '{element_type}'" ) if output_format == "line" and len(column_names) > 1: raise ValueError( f"'{output_format}' output_format can have only 1 column, " f"not {len(column_names)}" ) # This method expects a list of objects for gap detection if method in ["delta", "deltagaps", "gran"]: if not columns: if output_format == "list": # Only one column is needed. columns = ["id"] else: columns = ["id", "name"] if element_type == "stvds": columns.append("layer") columns.extend( [ "mapset", "start_time", "end_time", "interval_length", "distance_from_begin", ] ) check_columns( column_names=columns, output_format=output_format, element_type=element_type, ) rows = _get_list_of_maps_delta_gran( dataset=dataset, columns=columns, where=where, method=method, gran=gran, dbif=dbif, msgr=msgr, ) else: if columns: check_columns( column_names=columns, output_format=output_format, element_type=element_type, ) else: if output_format == "line": # For list of values, only one column is needed. columns = ["id"] else: columns = ["name", "mapset", "start_time", "end_time"] if not order: order = "start_time" rows = dataset.get_registered_maps(",".join(columns), where, order, dbif) # End with error for the old, custom formats. Proper formats simply return # empty result whatever empty is for each format (e.g., empty list for JSON). if not rows and (output_format in ["plain", "line"]): dbif.close() gs.fatal( _( "Nothing found in the database for space time dataset <{name}> " "(type: {element_type}): {detail}" ).format( name=dataset.get_id(), element_type=element_type, detail=( _( "Dataset is empty or where clause is too constrained or " "incorrect" ) if where else _("Dataset is empty") ), ) ) if connection_state_changed: dbif.close() return rows, columns # The code is compatible with pre-v8.2 versions, but for v9, it needs to be reviewed # to remove the backwards compatibility which will clean it up.
[docs]def list_maps_of_stds( type, # pylint: disable=redefined-builtin input, # pylint: disable=redefined-builtin columns, order, where, separator, method, no_header=False, gran=None, dbif=None, outpath=None, output_format=None, ): """List the maps of a space time dataset using different methods :param type: The type of the maps raster, raster3d or vector :param input: Name of a space time raster dataset :param columns: A comma separated list of columns to be printed to stdout :param order: A comma separated list of columns to order the maps by category :param where: A where statement for selected listing without "WHERE" e.g: start_time < "2001-01-01" and end_time > "2001-01-01" :param separator: The field separator character between the columns :param method: String identifier to select a method out of cols, comma,delta or deltagaps :param dbif: The database interface to be used - "cols" Print preselected columns specified by columns - "comma" Print the map ids ("name@mapset") as comma separated string - "delta" Print the map ids ("name@mapset") with start time, end time, relative length of intervals and the relative distance to the begin - "deltagaps" Same as "delta" with additional listing of gaps. Gaps can be easily identified as the id is "None" - "gran" List map using the granularity of the space time dataset, columns are identical to deltagaps :param no_header: Suppress the printing of column names :param gran: The user defined granule to be used if method=gran is set, in case gran=None the granule of the space time dataset is used :param outpath: The path to file where to save output """ if not output_format: if method == "comma": output_format = "line" output_format = "plain" if columns: if isinstance(columns, str): columns = columns.split(",") rows, columns = _get_list_of_maps_stds( element_type=type, name=input, columns=columns, order=order, where=where, method=method, output_format=output_format, gran=gran, dbif=dbif, ) if output_format == "line": _write_line( items=[row[0] for row in rows], separator=separator, file=outpath, ) else: _write_table( rows=rows, column_names=None if no_header else columns, separator=separator, output_format=output_format, file=outpath, )
############################################################################### if __name__ == "__main__": import doctest doctest.testmod()