earthengine-api 1.6.11__py3-none-any.whl → 1.6.12rc0__py3-none-any.whl

ee/cli/commands.py

@@ -69,7 +69,7 @@ TYPE_STRING = 'string'
 SYSTEM_TIME_START = 'system:time_start'
 SYSTEM_TIME_END = 'system:time_end'
 
-# A regex that parses properties of the form "[(type)]name=value".  The
+# A regex that parses properties of the form "[(type)]name=value". The
 # second, third, and fourth group are type, name, and number, respectively.
 PROPERTY_RE = re.compile(r'(\(([^\)]*)\))?([^=]+)=(.*)')
 
@@ -193,6 +193,39 @@ def _cloud_timestamp_for_timestamp_ms(timestamp_ms: float) -> str:
   return timestamp.replace(tzinfo=None).isoformat() + 'Z'
 
 
+def _datetime_from_cloud_timestamp(
+    cloud_timestamp: str | None,
+) -> datetime.datetime:
+  """Returns a datetime object for the given Cloud-formatted timestamp.
+
+  Args:
+    cloud_timestamp: A timestamp string in the format 'YYYY-MM-DDTHH:MM:SS.mmmZ'
+      or 'YYYY-MM-DDTHH:MM:SSZ'. If None, returns the epoch.
+
+  Returns:
+    A datetime object for the given Cloud-formatted timestamp. If the timestamp
+    is None, returns the epoch.
+  """
+  if not cloud_timestamp:
+    return datetime.datetime.fromtimestamp(0)
+  # Replace 'Z' with the UTC offset +00:00 for fromisoformat compatibility.
+  return datetime.datetime.fromisoformat(cloud_timestamp.replace('Z', '+00:00'))
+
+
+def _format_cloud_timestamp(timestamp: str | None) -> str:
+  """Returns a formatted datetime for the given Cloud-formatted timestamp.
+
+  Args:
+    timestamp: A timestamp string in the format 'YYYY-MM-DDTHH:MM:SS.mmmZ'
+      or 'YYYY-MM-DDTHH:MM:SSZ'.
+
+  Returns:
+    A formatted datetime string in the format 'YYYY-MM-DD HH:MM:SS'. If the
+    timestamp is None, returns the formatted epoch.
+  """
+  return _datetime_from_cloud_timestamp(timestamp).strftime('%Y-%m-%d %H:%M:%S')
+
+
 def _parse_millis(millis: float) -> datetime.datetime:
   return datetime.datetime.fromtimestamp(millis / 1000)
 
@@ -230,13 +263,34 @@ def _decode_date(string: str) -> Union[float, str]:
       'Invalid value for property of type "date": "%s".' % string)
 
 
+def _task_id_to_operation_name(task_id: str) -> str:
+  """Converts a task ID to an operation name."""
+  # pylint: disable=protected-access
+  return ee._cloud_api_utils.convert_task_id_to_operation_name(
+      ee.data._get_state().cloud_api_user_project, task_id
+  )
+  # pylint: enable=protected-access
+
+
+def _operation_name_to_task_id(operation_name: str) -> str:
+  """Converts an operation name to a task ID."""
+  # pylint: disable-next=protected-access
+  return ee._cloud_api_utils.convert_operation_name_to_task_id(operation_name)
+
+
+def _convert_to_operation_state(state: str) -> str:
+  """Converts a task or operation state to an operation state."""
+  # pylint: disable-next=protected-access
+  return ee._cloud_api_utils.convert_to_operation_state(state)
+
+
 def _decode_property(string: str) -> tuple[str, Any]:
   """Decodes a general key-value property from a command-line argument.
 
   Args:
     string: The string must have the form name=value or (type)name=value, where
       type is one of 'number', 'string', or 'date'. The value format for dates
-      is YYYY-MM-DD[THH:MM:SS[.MS]].  The value 'null' is special: it evaluates
+      is YYYY-MM-DD[THH:MM:SS[.MS]]. The value 'null' is special: it evaluates
       to None unless it is cast to a string of 'null'.
 
   Returns:
@@ -400,7 +454,7 @@ class AuthenticateCommand:
         args_auth['auth_mode'] = 'notebook'
 
     if ee.Authenticate(**args_auth):
-      print('Authenticate: Credentials already exist.  Use --force to refresh.')
+      print('Authenticate: Credentials already exist. Use --force to refresh.')
 
 
 class SetProjectCommand:
@@ -1111,19 +1165,21 @@ class TaskCancelCommand:
     config.ee_init()
     cancel_all = args.task_ids == ['all']
     if cancel_all:
-      statuses = ee.data.getTaskList()
+      operations = ee.data.listOperations()
     else:
-      statuses = ee.data.getTaskStatus(args.task_ids)
-    for status in statuses:
-      state = status['state']
-      task_id = status['id']
+      operation_names = map(_task_id_to_operation_name, args.task_ids)
+      operations = map(ee.data.getOperation, operation_names)
+    for operation in operations:
+      name = operation['name']
+      state = operation['metadata']['state']
+      task_id = _operation_name_to_task_id(name)
       if state == 'UNKNOWN':
-        raise ee.EEException('Unknown task id "%s"' % task_id)
-      elif state == 'READY' or state == 'RUNNING':
-        print('Canceling task "%s"' % task_id)
-        ee.data.cancelTask(task_id)
+        raise ee.EEException(f'Unknown task id "{task_id}"')
+      elif state == 'PENDING' or state == 'RUNNING':
+        print(f'Canceling task "{task_id}"')
+        ee.data.cancelOperation(name)
       elif not cancel_all:
-        print('Task "{}" already in state "{}".'.format(status['id'], state))
+        print(f'Task "{task_id}" already in state "{state}".')
 
 
 class TaskInfoCommand:
@@ -1139,26 +1195,30 @@ class TaskInfoCommand:
   ) -> None:
     """Runs the TaskInfo command."""
     config.ee_init()
-    for i, status in enumerate(ee.data.getTaskStatus(args.task_id)):
+    for i, task_id in enumerate(args.task_id):
+      operation = ee.data.getOperation(_task_id_to_operation_name(task_id))
       if i:
         print()
-      print('%s:' % status['id'])
-      print('  State: %s' % status['state'])
-      if status['state'] == 'UNKNOWN':
+      print(f'{task_id}:')
+      metadata = operation['metadata']
+      state = metadata['state']
+      print(f'  State: {state}')
+      if state == 'UNKNOWN':
         continue
-      print('  Type: %s' % TASK_TYPES.get(status.get('task_type'), 'Unknown'))
-      print('  Description: %s' % status.get('description'))
-      print('  Created: %s' % _parse_millis(status['creation_timestamp_ms']))
-      if 'start_timestamp_ms' in status:
-        print('  Started: %s' % _parse_millis(status['start_timestamp_ms']))
-      if 'update_timestamp_ms' in status:
-        print('  Updated: %s' % _parse_millis(status['update_timestamp_ms']))
-      if 'error_message' in status:
-        print('  Error: %s' % status['error_message'])
-      if 'destination_uris' in status:
-        print('  Destination URIs: %s' % ', '.join(status['destination_uris']))
-      if 'priority' in status:
-        print('  Priority: %s' % status['priority'])
+      print(f'  Type: {TASK_TYPES.get(metadata.get("type"), "Unknown")}')
+      print(f'  Description: {metadata.get("description")}')
+      print(f'  Created: {_format_cloud_timestamp(metadata["createTime"])}')
+      if start_time := metadata.get('startTime'):
+        print(f'  Started: {_format_cloud_timestamp(start_time)}')
+      if update_time := metadata.get('updateTime'):
+        print(f'  Updated: {_format_cloud_timestamp(update_time)}')
+      if error := operation.get('error'):
+        if error_message := error.get('message'):
+          print(f'  Error: {error_message}')
+      if destination_uris := metadata.get('destinationUris'):
+        print(f'  Destination URIs: {destination_uris}')
+      if priority := metadata.get('priority'):
+        print(f'  Priority: {priority}')
 
 
 class TaskListCommand:
@@ -1168,10 +1228,27 @@ class TaskListCommand:
 
   def __init__(self, parser: argparse.ArgumentParser):
     parser.add_argument(
-        '--status', '-s', required=False, nargs='*',
-        choices=['READY', 'RUNNING', 'COMPLETED', 'FAILED',
-                 'CANCELLED', 'UNKNOWN'],
-        help=('List tasks only with a given status'))
+        '--status',
+        '-s',
+        required=False,
+        nargs='*',
+        choices=[
+            'CANCELLED',
+            'CANCELLING',
+            'COMPLETED',  # Kept for backward compatibility.
+            'FAILED',
+            'PENDING',
+            'READY',  # Kept for backward compatibility.
+            'RUNNING',
+            'SUCCEEDED',
+            'UNKNOWN',
+        ],
+        help=(
+            'List tasks only with a given status. Note: for backward'
+            ' compatibility, "READY" is an alias for "PENDING" and "COMPLETED"'
+            ' is an alias for "SUCCEEDED".'
+        ),
+    )
     parser.add_argument(
         '--long_format',
         '-l',
@@ -1185,34 +1262,47 @@ class TaskListCommand:
   ) -> None:
     """Lists tasks present for a user, maybe filtering by state."""
     config.ee_init()
-    status = args.status
-    tasks = ee.data.getTaskList()
-    descs = [utils.truncate(task.get('description', ''), 40) for task in tasks]
+    status = list(
+        map(_convert_to_operation_state, args.status) if args.status else []
+    )
+    operations = ee.data.listOperations()
+    descs = [
+        utils.truncate(op.get('metadata', {}).get('description', ''), 40)
+        for op in operations
+    ]
     desc_length = max((len(word) for word in descs), default=0)
-    format_str = '{:25s} {:13s} {:%ds} {:10s} {:s}' % (desc_length + 1)
-    for task in tasks:
-      if status and task['state'] not in status:
+    format_str = f'{{:25s}} {{:13s}} {{:{desc_length + 1}s}} {{:10s}} {{:s}}'
+    for operation in operations:
+      metadata = operation['metadata']
+      if status and metadata['state'] not in status:
         continue
-      truncated_desc = utils.truncate(task.get('description', ''), 40)
-      task_type = TASK_TYPES.get(task['task_type'], 'Unknown')
+      truncated_desc = utils.truncate(metadata.get('description', ''), 40)
+      task_type = TASK_TYPES.get(metadata['type'], 'Unknown')
       extra = ''
       if args.long_format:
-        show_date = lambda ms: _parse_millis(ms).strftime('%Y-%m-%d %H:%M:%S')
-        eecu = '{:.4f}'.format(
-            task['batch_eecu_usage_seconds']
-        ) if 'batch_eecu_usage_seconds' in task else '-'
-        trailing_extras = task.get('destination_uris', [])
-        trailing_extras.append(task.get('priority', '-'))
+        if eecu := metadata.get('batchEecuUsageSeconds'):
+          eecu = f'{eecu:.4f}'
+        else:
+          eecu = '-'
+        trailing_extras = metadata.get('destination_uris', [])
+        trailing_extras.append(metadata.get('priority', '-'))
         extra = ' {:20s} {:20s} {:20s} {:11s} {}'.format(
-            show_date(task['creation_timestamp_ms']),
-            show_date(task['start_timestamp_ms']),
-            show_date(task['update_timestamp_ms']),
+            _format_cloud_timestamp(operation.get('createTime')),
+            _format_cloud_timestamp(operation.get('startTime')),
+            _format_cloud_timestamp(operation.get('updateTime')),
             eecu,
             ' '.join(map(str, trailing_extras)),
         )
-      print(format_str.format(
-          task['id'], task_type, truncated_desc,
-          task['state'], task.get('error_message', '---')) + extra)
+      print(
+          format_str.format(
+              _operation_name_to_task_id(operation['name']),
+              task_type,
+              truncated_desc,
+              metadata['state'],
+              operation.get('error', {}).get('message', '---'),
+          )
+          + extra
+      )
 
 
 class TaskWaitCommand:
@@ -1241,17 +1331,17 @@ class TaskWaitCommand:
     config.ee_init()
     task_ids = []
     if args.task_ids == ['all']:
-      tasks = ee.data.getTaskList()
-      for task in tasks:
-        if task['state'] not in utils.TASK_FINISHED_STATES:
-          task_ids.append(task['id'])
+      operations = ee.data.listOperations()
+      for operation in operations:
+        if not operation.get('done', False):
+          task_ids.append(_operation_name_to_task_id(operation['name']))
     else:
-      statuses = ee.data.getTaskStatus(args.task_ids)
-      for status in statuses:
-        state = status['state']
-        task_id = status['id']
+      for task_id in args.task_ids:
+        operation = ee.data.getOperation(_task_id_to_operation_name(task_id))
+        state = operation['metadata']['state']
+        task_id = _operation_name_to_task_id(operation['name'])
         if state == 'UNKNOWN':
-          raise ee.EEException('Unknown task id "%s"' % task_id)
+          raise ee.EEException(f'Unknown task id "{task_id}"')
         else:
           task_ids.append(task_id)
 

ee/cli/eecli.py

@@ -35,7 +35,7 @@ def _run_command(*argv):
       'Defaults to "~/%s".' % utils.DEFAULT_EE_CONFIG_FILE_RELATIVE)
   parser.add_argument(
       '--service_account_file', help='Path to a service account credentials'
-      'file.  Overrides any ee_config if specified.')
+      'file. Overrides any ee_config if specified.')
   parser.add_argument(
       '--project',
       help='Specifies a Google Cloud Platform Project id to override the call.',

ee/cli/utils.py

@@ -40,12 +40,6 @@ CONFIG_PARAMS: dict[str, Union[str, list[str], None]] = {
     'url': 'https://earthengine.googleapis.com',
 }
 
-TASK_FINISHED_STATES: tuple[str, str, str] = (
-    ee.batch.Task.State.COMPLETED,
-    ee.batch.Task.State.FAILED,
-    ee.batch.Task.State.CANCELLED,
-)
-
 
 class CommandLineConfig:
   """Holds the configuration parameters used by the EE command line interface.
@@ -248,6 +242,15 @@ def truncate(string: str, length: int) -> str:
     return string
 
 
+def _task_id_to_operation_name(task_id: str) -> str:
+  """Converts a task ID to an operation name."""
+  # pylint: disable=protected-access
+  return ee._cloud_api_utils.convert_task_id_to_operation_name(
+      ee.data._get_state().cloud_api_user_project, task_id
+  )
+  # pylint: enable=protected-access
+
+
 def wait_for_task(
     task_id: str, timeout: float, log_progress: bool = True
 ) -> None:
@@ -257,10 +260,10 @@ def wait_for_task(
   last_check = 0
   while True:
     elapsed = time.time() - start
-    status = ee.data.getTaskStatus(task_id)[0]
-    state = status['state']
-    if state in TASK_FINISHED_STATES:
-      error_message = status.get('error_message', None)
+    status = ee.data.getOperation(_task_id_to_operation_name(task_id))
+    state = status['metadata']['state']
+    if status.get('done', False):
+      error_message = status.get('error', {}).get('message')
       print('Task %s ended at state: %s after %.2f seconds'
             % (task_id, state, elapsed))
       if error_message:
@@ -299,14 +302,21 @@ def wait_for_tasks(
   for thread in threads:
     thread.join()
 
-  status_list = ee.data.getTaskStatus(task_id_list)
+  get_state = lambda task_id: ee.data.getOperation(
+      _task_id_to_operation_name(task_id)
+  )['metadata']['state']
+  status_list = [get_state(task_id) for task_id in task_id_list]
   status_counts = collections.defaultdict(int)
   for status in status_list:
-    status_counts[status['state']] += 1
-  num_incomplete = (len(status_list) - status_counts['COMPLETED']
-                    - status_counts['FAILED'] - status_counts['CANCELLED'])
+    status_counts[status] += 1
+  num_incomplete = (
+      len(status_list)
+      - status_counts['SUCCEEDED']
+      - status_counts['FAILED']
+      - status_counts['CANCELLED']
+  )
   print('Finished waiting for tasks.\n  Status summary:')
-  print('  %d tasks completed successfully.' % status_counts['COMPLETED'])
+  print('  %d tasks completed successfully.' % status_counts['SUCCEEDED'])
   print('  %d tasks failed.' % status_counts['FAILED'])
   print('  %d tasks cancelled.' % status_counts['CANCELLED'])
   print('  %d tasks are still incomplete (timed-out)' % num_incomplete)

ee/collection.py

@@ -6,7 +6,7 @@ This class is never intended to be instantiated by the user.
 from __future__ import annotations
 
 import datetime
-from typing import Any, Callable
+from typing import Any, Callable, Generic, TypeVar
 
 from ee import _arg_types
 from ee import _utils
@@ -26,8 +26,14 @@ from ee import function
 from ee import geometry as ee_geometry
 from ee import image
 
+# TODO: Remove this TypeVar and replace with typing.Self once
+# Python 3.11 is the minimum version.
+T = TypeVar('T', bound='Collection')
 
-class Collection(element.Element):
+ElementType = TypeVar('ElementType')
+
+
+class Collection(Generic[ElementType], element.Element):
   """Base class for ImageCollection and FeatureCollection."""
 
   _initialized = False
@@ -442,7 +448,7 @@ class Collection(element.Element):
         'Collection.errorMatrix', self, actual, predicted, order
     )
 
-  def filter(self, new_filter: str | ee_filter.Filter) -> Any:
+  def filter(self: T, new_filter: str | ee_filter.Filter) -> T:
     """Apply a filter to this collection.
 
     Args:
@@ -459,8 +465,8 @@ class Collection(element.Element):
 
   @deprecation.CanUseDeprecated
   def filterMetadata(
-      self, name: str, operator: str, value: int | str
-  ) -> Any:
+      self: T, name: str, operator: str, value: int | str
+  ) -> T:
     """Shortcut to add a metadata filter to a collection.
 
     This is equivalent to self.filter(Filter().metadata(...)).
@@ -468,7 +474,7 @@ class Collection(element.Element):
     Args:
       name: Name of a property to filter.
       operator: Name of a comparison operator as defined
-          by FilterCollection.  Possible values are: "equals", "less_than",
+          by FilterCollection. Possible values are: "equals", "less_than",
           "greater_than", "not_equals", "not_less_than", "not_greater_than",
           "starts_with", "ends_with", "not_starts_with", "not_ends_with",
           "contains", "not_contains".
@@ -480,8 +486,13 @@ class Collection(element.Element):
     return self.filter(ee_filter.Filter.metadata_(name, operator, value))
 
   def filterBounds(
-      self, geometry: dict[str, Any] | ee_geometry.Geometry
-  ) -> Any:
+      self: T,
+      geometry: (
+          dict[str, Any]
+          | ee_geometry.Geometry
+          | featurecollection.FeatureCollection
+      ),
+  ) -> T:
     """Shortcut to add a geometry filter to a collection.
 
     Items in the collection with a footprint that fails to intersect
@@ -505,12 +516,10 @@ class Collection(element.Element):
   # TODO(user): Any --> DateRange
   @_utils.accept_opt_prefix('opt_end')
   def filterDate(
-      self,
+      self: T,
       start: datetime.datetime | ee_date.Date | int | str | Any,
-      end: None | (
-          datetime.datetime | ee_date.Date | int | str | Any
-      ) = None,
-  ) -> Any:
+      end: None | (datetime.datetime | ee_date.Date | int | str | Any) = None,
+  ) -> T:
     """Shortcut to filter a collection with a date range.
 
     Items in the collection with a system:time_start property that doesn't
@@ -529,7 +538,7 @@ class Collection(element.Element):
     """
     return self.filter(ee_filter.Filter.date(start, end))
 
-  def first(self) -> element.Element:
+  def first(self) -> ElementType:
     """Returns the first entry from a given collection."""
 
     return apifunction.ApiFunction.call_('Collection.first', self)
@@ -660,10 +669,10 @@ class Collection(element.Element):
   # TODO(user): Can dropNulls default to False?
   @_utils.accept_opt_prefix('opt_dropNulls')
   def map(
-      self,
+      self: T,
       algorithm: Callable[[Any], Any],
       dropNulls: bool | None = None,  # pylint: disable=invalid-name
-  ) -> Any:
+  ) -> T:
     """Maps an algorithm over a collection.
 
     Args:
@@ -822,12 +831,12 @@ class Collection(element.Element):
 
   # TODO(user): Make ascending default to True
   @_utils.accept_opt_prefix('opt_ascending')
-  def sort(self, prop: str, ascending: bool | None = None) -> Any:
+  def sort(self: T, prop: str, ascending: bool | None = None) -> T:
     """Sort a collection by the specified property.
 
     Args:
        prop: The property to sort by.
-       ascending: Whether to sort in ascending or descending order.  The default
+       ascending: Whether to sort in ascending or descending order. The default
          is true (ascending).
 
     Returns:

ee/computedobject.py

@@ -38,11 +38,11 @@ class ComputedObject(encodable.Encodable, metaclass=ComputedObjectMetaclass):
   necessary to interact well with the rest of the API.
 
   ComputedObjects come in two flavors:
-  1. If func != null and args != null, the ComputedObject is encoded as an
-     invocation of func with args.
-  2. If func == null and args == null, the ComputedObject is a variable
+  1. If func is not None and args is not None, the ComputedObject is encoded as
+     an invocation of func with args.
+  2. If func is None and args is None, the ComputedObject is a variable
      reference. The variable name is stored in its varName member. Note that
-     in this case, varName may still be null; this allows the name to be
+     in this case, varName may still be None; this allows the name to be
      deterministically generated at a later time. This is used to generate
      deterministic variable names for mapped functions, ensuring that nested
      mapping calls do not use the same variable name.
@@ -184,7 +184,7 @@ class ComputedObject(encodable.Encodable, metaclass=ComputedObjectMetaclass):
 
   def __str__(self) -> str:
     """Writes out the object in a human-readable form."""
-    return 'ee.{}({})'.format(self.name(), serializer.toReadableJSON(self))
+    return f'ee.{self.name()}({serializer.toReadableJSON(self)})'
 
   def isVariable(self) -> bool:
     """Returns whether this computed object is a variable reference."""

ee/customfunction.py

@@ -171,19 +171,19 @@ class CustomFunction(function.Function, encodable.Encodable):
       return CountNodes(expression['values'].values())
 
     # There are three function building phases, which each call body():
-    # 1 - Check Return.  The constructor verifies that body() returns a result,
+    # 1 - Check Return. The constructor verifies that body() returns a result,
     # but does not try to serialize the result. If the function tries to use
     # unbound variables (e.g., using .getInfo() or print()), ComputedObject will
     # throw an exception when these calls try to serialize themselves, so that
     # unbound variables are not passed in server calls.
-    # 2 - Count Functions.  We serialize the result here. At this point all
+    # 2 - Count Functions. We serialize the result here. At this point all
     # variables must have names for serialization to succeed, but we don't yet
     # know the correct function depth. So we serialize with unbound_name set to
     # '<unbound>', which should silently succeed. If this does end up in server
     # calls, the function is very unusual: the first call doesn't use unbound
     # variables but the second call does. In this rare case we will return
     # server errors complaining about <unbound>.
-    # 3 - Final Serialize.  Finally, the constructor calls body() with the
+    # 3 - Final Serialize. Finally, the constructor calls body() with the
     # correct, depth-dependent names, which are used when the CustomFunction
     # is serialized and sent to the server.
     serialized_body = serializer.encode(