earthengine-api 1.5.13rc0__py3-none-any.whl → 1.7.4__py3-none-any.whl

ee/batch.py

@@ -9,10 +9,11 @@ The public function styling uses camelCase to match the JavaScript names.
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 import enum
 import json
 import re
-from typing import Any, Dict, List, Optional, Sequence, Union
+from typing import Any
 
 from ee import _cloud_api_utils
 from ee import data
@@ -20,7 +21,7 @@ from ee import ee_exception
 from ee import geometry
 
 
-def _transform_operation_to_task(operation: Dict[str, Any]) -> Task:
+def _transform_operation_to_task(operation: dict[str, Any]) -> Task:
   """Converts an operation to a task."""
   status = _cloud_api_utils.convert_operation_to_task(operation)
   return Task(
@@ -54,14 +55,14 @@ class Task:
     CANCELLED = 'CANCELLED'
 
     @classmethod
-    def active(cls, state: Union[str, Task.State]) -> bool:
+    def active(cls, state: str | Task.State) -> bool:
       """Returns True if the given state is an active one."""
       if isinstance(state, str):
         state = cls(state)
       return state in (cls.READY, cls.RUNNING, cls.CANCEL_REQUESTED)
 
     @classmethod
-    def success(cls, state: Union[str, Task.State]) -> bool:
+    def success(cls, state: str | Task.State) -> bool:
       """Returns True if the given state indicates a completed task."""
       if isinstance(state, str):
         state = cls(state)
@@ -74,22 +75,22 @@ class Task:
     FEATURE_VIEW = 'FEATURE_VIEW'
     BIGQUERY = 'BIGQUERY'
 
-  config: Optional[Dict[str, Any]]
-  id: Optional[str]
-  name: Optional[str]
+  config: dict[str, Any] | None
+  id: str | None
+  name: str | None
   state: State
   task_type: Type
-  workload_tag: Optional[Union[int, str]]
+  workload_tag: int | str | None
 
-  _request_id: Optional[str]
+  _request_id: str | None
 
   def __init__(
       self,
-      task_id: Optional[str],
+      task_id: str | None,
       task_type: Type,
       state: State,
-      config: Optional[Dict[str, Any]] = None,
-      name: Optional[str] = None,
+      config: dict[str, Any] | None = None,
+      name: str | None = None,
   ):
     """Creates a Task with the given ID and configuration.
 
@@ -99,7 +100,7 @@ class Task:
     - Unpickling a previously pickled Task object.
 
     If you're looking for a task's status but don't need a full task object,
-    ee.data.getTaskStatus() may be appropriate.
+    ee.data.getOperation() may be appropriate.
 
     Args:
       task_id: The task ID, originally obtained through ee.data.newTaskId().
@@ -111,7 +112,7 @@ class Task:
           - description: The name of the task, a freeform string.
           - sourceUrl: An optional URL for the script that generated the task.
           Specific task types have other custom config fields.
-      name: The name of the operation.  Only relevant when using the cloud api.
+      name: The name of the operation.
     """
     self.id = self._request_id = task_id
     self.config = config and config.copy()
@@ -121,11 +122,10 @@ class Task:
     self.name = name
 
   @property
-  def operation_name(self) -> Optional[str]:
+  def operation_name(self) -> str | None:
+    """The server-assigned name for this task."""
     if self.name:
       return self.name
-    if self.id:
-      return _cloud_api_utils.convert_task_id_to_operation_name(self.id)
     return None
 
   def start(self) -> None:
@@ -152,14 +152,13 @@ class Task:
     elif self.task_type == Task.Type.EXPORT_CLASSIFIER:
       result = data.exportClassifier(self._request_id, self.config)
     else:
-      raise ee_exception.EEException(
-          'Unknown Task type "{}"'.format(self.task_type))
+      raise ee_exception.EEException(f'Unknown Task type "{self.task_type}"')
     if not self.id:
       self.id = _cloud_api_utils.convert_operation_name_to_task_id(
           result['name'])
       self.name = result['name']
 
-  def status(self) -> Dict[str, Any]:
+  def status(self) -> dict[str, Any]:
     """Fetches the current status of the task.
 
     Returns:
@@ -190,7 +189,7 @@ class Task:
     data.cancelOperation(self.operation_name)
 
   @staticmethod
-  def list() -> List[Task]:
+  def list() -> list[Task]:
     """Returns the tasks submitted to EE by the current user.
 
     These include all currently running tasks as well as recently canceled or
@@ -204,11 +203,13 @@ class Task:
   def __repr__(self) -> str:
     """Returns a string representation of the task."""
     if self.config and self.id:
-      return '<Task %s %s: %s (%s)>' % (self.id, self.task_type,
-                                        self.config['description'], self.state)
+      return '<Task {} {}: {} ({})>'.format(
+          self.id, self.task_type, self.config['description'], self.state
+      )
     elif self.config:
-      return '<Task %s: %s (%s)>' % (self.task_type, self.config['description'],
-                                     self.state)
+      return '<Task {}: {} ({})>'.format(
+          self.task_type, self.config['description'], self.state
+      )
     else:
       return '<Task "%s">' % self.id
 
@@ -231,7 +232,7 @@ class Export:
         cls,
         image: Any,
         description: str = 'myExportImageTask',
-        config: Optional[Dict[str, Any]] = None,
+        config: dict[str, Any] | None = None,
     ):
       """Creates a task to export an EE Image to Google Drive or Cloud Storage.
 
@@ -307,6 +308,7 @@ class Export:
         crsTransform=None,
         maxPixels=None,
         priority=None,
+        overwrite=False,
         **kwargs,
     ) -> Task:
       """Creates a task to export an EE Image to an EE Asset.
@@ -343,6 +345,7 @@ class Export:
         priority: The priority of the task within the project. Higher priority
           tasks are scheduled sooner. Must be an integer between 0 and 9999.
           Defaults to 100.
+        overwrite: If an existing asset can be overwritten by this export.
         **kwargs: Holds other keyword arguments that may have been deprecated
             such as 'crs_transform'.
 
@@ -738,6 +741,7 @@ class Export:
         assetId=None,
         maxVertices=None,
         priority=None,
+        overwrite=False,
         **kwargs,
     ) -> Task:
       """Creates a task to export a FeatureCollection to an EE table asset.
@@ -752,6 +756,7 @@ class Export:
         priority: The priority of the task within the project. Higher priority
           tasks are scheduled sooner. Must be an integer between 0 and 9999.
           Defaults to 100.
+        overwrite: If an existing asset can be overwritten by this export.
         **kwargs: Holds other keyword arguments that may have been deprecated.
 
       Returns:
@@ -762,6 +767,7 @@ class Export:
           'assetId': assetId,
           'maxVertices': maxVertices,
           'priority': priority,
+          'overwrite': overwrite,
       }
       config = {k: v for k, v, in config.items() if v is not None}
       config = _prepare_table_export_config(collection, config,
@@ -1152,8 +1158,8 @@ NON_FILE_DESTINATIONS = frozenset([
 
 
 def _prepare_image_export_config(
-    image: Any, config: Dict[str, Any], export_destination: str
-) -> Dict[str, Any]:
+    image: Any, config: dict[str, Any], export_destination: str
+) -> dict[str, Any]:
   """Performs all preparation steps for an image export.
 
   Args:
@@ -1231,15 +1237,14 @@ def _prepare_image_export_config(
   if config:
     if 'skipEmptyTiles' in config:
       raise ValueError('skipEmptyTiles is only supported for GeoTIFF exports.')
-    raise ee_exception.EEException(
-        'Unknown configuration options: {}.'.format(config))
+    raise ee_exception.EEException(f'Unknown configuration options: {config}.')
 
   return request
 
 
 def _prepare_map_export_config(
-    image: Any, config: Dict[str, Any]
-) -> Dict[str, Any]:
+    image: Any, config: dict[str, Any]
+) -> dict[str, Any]:
   """Performs all preparation steps for a map export.
 
   Args:
@@ -1279,14 +1284,13 @@ def _prepare_map_export_config(
     # for JSON encoding.
     request['priority'] = {'value': int(config.pop('priority'))}
   if config:
-    raise ee_exception.EEException(
-        'Unknown configuration options: {}.'.format(config))
+    raise ee_exception.EEException(f'Unknown configuration options: {config}.')
   return request
 
 
 def _prepare_table_export_config(
-    collection: Any, config: Dict[str, Any], export_destination
-) -> Dict[str, Any]:
+    collection: Any, config: dict[str, Any], export_destination
+) -> dict[str, Any]:
   """Performs all preparation steps for a table export.
 
   Args:
@@ -1351,14 +1355,13 @@ def _prepare_table_export_config(
     request['priority'] = {'value': int(config.pop('priority'))}
 
   if config:
-    raise ee_exception.EEException(
-        'Unknown configuration options: {}.'.format(config))
+    raise ee_exception.EEException(f'Unknown configuration options: {config}.')
   return request
 
 
 def _prepare_video_export_config(
-    collection: Any, config: Dict[str, Any], export_destination: str
-) -> Dict[str, Any]:
+    collection: Any, config: dict[str, Any], export_destination: str
+) -> dict[str, Any]:
   """Performs all preparation steps for a video export.
 
   Args:
@@ -1394,14 +1397,13 @@ def _prepare_video_export_config(
     request['priority'] = {'value': int(config.pop('priority'))}
 
   if config:
-    raise ee_exception.EEException(
-        'Unknown configuration options: {}.'.format(config))
+    raise ee_exception.EEException(f'Unknown configuration options: {config}.')
   return request
 
 
 def _build_image_file_export_options(
-    config: Dict[str, Any], export_destination: str
-) -> Dict[str, Any]:
+    config: dict[str, Any], export_destination: str
+) -> dict[str, Any]:
   """Builds an ImageFileExportOptions from values in a config dict.
 
   Args:
@@ -1427,7 +1429,8 @@ def _build_image_file_export_options(
             config)
   else:
     raise ee_exception.EEException(
-        '"{}" is not a valid export destination'.format(export_destination))
+        f'"{export_destination}" is not a valid export destination'
+    )
 
   file_format_options = config.pop(IMAGE_FORMAT_OPTIONS_FIELD, {})
 
@@ -1499,14 +1502,15 @@ def _build_image_file_export_options(
 
   if file_format_options:
     raise ee_exception.EEException(
-        'Unknown file format options: {}.'.format(file_format_options))
+        f'Unknown file format options: {file_format_options}.'
+    )
 
   return file_export_options
 
 
 def _build_table_file_export_options(
-    config: Dict[str, Any], export_destination: str
-) -> Dict[str, Any]:
+    config: dict[str, Any], export_destination: str
+) -> dict[str, Any]:
   """Builds a TableFileExportOptions from values in a config dict.
 
   Args:
@@ -1531,11 +1535,12 @@ def _build_table_file_export_options(
             config)
   else:
     raise ee_exception.EEException(
-        '"{}" is not a valid export destination'.format(export_destination))
+        f'"{export_destination}" is not a valid export destination'
+    )
   return file_export_options
 
 
-def _build_video_options(config: Dict[str, Any]) -> Dict[str, Any]:
+def _build_video_options(config: dict[str, Any]) -> dict[str, Any]:
   """Builds a VideoOptions from values in a config dict.
 
   Args:
@@ -1558,8 +1563,8 @@ def _build_video_options(config: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def _build_video_file_export_options(
-    config: Dict[str, Any], export_destination: str
-) -> Dict[str, Any]:
+    config: dict[str, Any], export_destination: str
+) -> dict[str, Any]:
   """Builds a VideoFileExportOptions from values in a config dict.
 
   Args:
@@ -1584,13 +1589,14 @@ def _build_video_file_export_options(
             config)
   else:
     raise ee_exception.EEException(
-        '"{}" is not a valid export destination'.format(export_destination))
+        f'"{export_destination}" is not a valid export destination'
+    )
   return file_export_options
 
 
 def _prepare_classifier_export_config(
-    classifier: Any, config: Dict[str, Any], export_destination: str
-) -> Dict[str, Any]:
+    classifier: Any, config: dict[str, Any], export_destination: str
+) -> dict[str, Any]:
   """Performs all preparation steps for a classifier export.
 
   Args:
@@ -1620,7 +1626,7 @@ def _prepare_classifier_export_config(
   return request
 
 
-def _build_drive_destination(config: Dict[str, Any]) -> Dict[str, Any]:
+def _build_drive_destination(config: dict[str, Any]) -> dict[str, Any]:
   """Builds a DriveDestination from values in a config dict.
 
   Args:
@@ -1639,7 +1645,7 @@ def _build_drive_destination(config: Dict[str, Any]) -> Dict[str, Any]:
   return drive_destination
 
 
-def _build_cloud_storage_destination(config: Dict[str, Any]) -> Dict[str, Any]:
+def _build_cloud_storage_destination(config: dict[str, Any]) -> dict[str, Any]:
   """Builds a CloudStorageDestination from values in a config dict.
 
   Args:
@@ -1660,7 +1666,7 @@ def _build_cloud_storage_destination(config: Dict[str, Any]) -> Dict[str, Any]:
   return destination
 
 
-def _build_bigquery_destination(config: Dict[str, Any]) -> Dict[str, Any]:
+def _build_bigquery_destination(config: dict[str, Any]) -> dict[str, Any]:
   """Builds a BigqueryDestination from values in a config dict.
 
   Args:
@@ -1679,7 +1685,7 @@ def _build_bigquery_destination(config: Dict[str, Any]) -> Dict[str, Any]:
   return destination
 
 
-def _build_tile_options(config: Dict[str, Any]) -> Dict[str, Any]:
+def _build_tile_options(config: dict[str, Any]) -> dict[str, Any]:
   """Builds a TileOptions from values in a config dict.
 
   Args:
@@ -1722,7 +1728,7 @@ def _build_tile_options(config: Dict[str, Any]) -> Dict[str, Any]:
   return tile_options
 
 
-def _build_earth_engine_destination(config: Dict[str, Any]) -> Dict[str, Any]:
+def _build_earth_engine_destination(config: dict[str, Any]) -> dict[str, Any]:
   """Builds an EarthEngineDestination from values in a config dict.
 
   Args:
@@ -1737,10 +1743,12 @@ def _build_earth_engine_destination(config: Dict[str, Any]) -> Dict[str, Any]:
       'name':
           _cloud_api_utils.convert_asset_id_to_asset_name(
               config.pop('assetId')),
+      'overwrite':
+          config.pop('overwrite', False)
   }
 
 
-def _build_feature_view_destination(config: Dict[str, Any]) -> Dict[str, Any]:
+def _build_feature_view_destination(config: dict[str, Any]) -> dict[str, Any]:
   """Builds a FeatureViewDestination from values in a config dict.
 
   Args:
@@ -1758,7 +1766,7 @@ def _build_feature_view_destination(config: Dict[str, Any]) -> Dict[str, Any]:
   return feature_view_destination
 
 
-def _get_rank_by_one_thing_rule(rule_str: str) -> Dict[str, Any]:
+def _get_rank_by_one_thing_rule(rule_str: str) -> dict[str, Any]:
   """Returns a RankByOneThingRule dict created from the rank-by-one-thing rule.
 
   Args:
@@ -1773,10 +1781,11 @@ def _get_rank_by_one_thing_rule(rule_str: str) -> Dict[str, Any]:
   matches = re.findall(r'^([\S]+.*)\s+(ASC|DESC)$', rule_str.strip())
   if not matches:
     raise ee_exception.EEException(
-        ('Ranking rule format is invalid. Each rule should be defined by a '
-         'rule type and a direction (ASC or DESC), separated by a space. '
-         'Valid rule types are: .geometryType, .minZoomLevel, or a feature '
-         'property name.'))
+        'Ranking rule format is invalid. Each rule should be defined by a '
+        'rule type and a direction (ASC or DESC), separated by a space. '
+        'Valid rule types are: .geometryType, .minZoomLevel, or a feature '
+        'property name.'
+    )
 
   output = {}
   rule_type, rule_dir = matches[0]
@@ -1796,8 +1805,8 @@ def _get_rank_by_one_thing_rule(rule_str: str) -> Dict[str, Any]:
 
 
 def _get_ranking_rule(
-    rules: Optional[Union[str, List[str]]]
-) -> Optional[Dict[str, List[Dict[str, Any]]]]:
+    rules: str | list[str] | None,
+) -> dict[str, list[dict[str, Any]]] | None:
   """Returns a RankingRule dict created from the rank-by-one-thing rules.
 
   Args:
@@ -1819,11 +1828,12 @@ def _get_ranking_rule(
     return {'rankByOneThingRule': rank_by_one_thing_rules}
 
   raise ee_exception.EEException(
-      ('Unable to build ranking rule from rules. Rules should '
-       'either be a comma-separated string or list of strings.'))
+      'Unable to build ranking rule from rules. Rules should '
+      'either be a comma-separated string or list of strings.'
+  )
 
 
-def _build_thinning_options(config: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+def _build_thinning_options(config: dict[str, Any]) -> dict[str, Any] | None:
   """Returns a ThinningOptions dict created from the config.
 
   Args:
@@ -1843,7 +1853,7 @@ def _build_thinning_options(config: Dict[str, Any]) -> Optional[Dict[str, Any]]:
   return output
 
 
-def _build_ranking_options(config: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+def _build_ranking_options(config: dict[str, Any]) -> dict[str, Any] | None:
   """Returns a RankingOptions dict created from the config.
 
   Args:
@@ -1869,8 +1879,8 @@ def _build_ranking_options(config: Dict[str, Any]) -> Optional[Dict[str, Any]]:
 
 
 def build_ingestion_time_parameters(
-    input_params: Dict[str, Any]
-) -> Dict[str, Any]:
+    input_params: dict[str, Any]
+) -> dict[str, Any]:
   """Builds a FeatureViewIngestionTimeParameters from values in a params dict.
 
   Args:
@@ -1898,7 +1908,7 @@ def build_ingestion_time_parameters(
   return output_params
 
 
-def _create_export_task(config: Dict[str, Any], task_type: Task.Type) -> Task:
+def _create_export_task(config: dict[str, Any], task_type: Task.Type) -> Task:
   """Creates an export task.
 
   Args:
@@ -1913,7 +1923,7 @@ def _create_export_task(config: Dict[str, Any], task_type: Task.Type) -> Task:
 
 def _capture_parameters(
     all_locals, parameters_to_exclude: Sequence[str]
-) -> Dict[str, Any]:
+) -> dict[str, Any]:
   """Creates a parameter dict by copying all non-None locals.
 
   This is generally invoked as the first part of call processing, via
@@ -2027,7 +2037,7 @@ def _canonicalize_parameters(config, destination):
 
 
 def _canonicalize_region(
-    region: Union[str, geometry.Geometry, Any]
+    region: str | geometry.Geometry | Any,
 ) -> geometry.Geometry:
   """Converts a region parameter to a form appropriate for export."""
   region_error = ee_exception.EEException(

ee/blob.py

@@ -1,7 +1,7 @@
 """A wrapper for Blobs."""
 from __future__ import annotations
 
-from typing import Any, Dict, Optional
+from typing import Any
 
 from ee import _arg_types
 from ee import apifunction
@@ -46,24 +46,22 @@ class Blob(computedobject.ComputedObject):
     """
     self.initialize()
 
-    args: Dict[str, Any] = {'url': url}
-    func = apifunction.ApiFunction(self.name())
-
-    if isinstance(url, str):
-      if not url.startswith('gs://'):
-        raise ValueError(f'{self.name()} url must start with "gs://": "{url}"')
-
-    elif isinstance(url, computedobject.ComputedObject):
+    if isinstance(url, computedobject.ComputedObject):
       if self.is_func_returning_same(url):
         # If it is a call that is already returning a Blob, just cast.
         super().__init__(url.func, url.args, url.varName)
         return
-
+    elif isinstance(url, str):
+      if not url.startswith('gs://'):
+        raise ValueError(f'{self.name()} url must start with "gs://": "{url}"')
     else:
       raise ValueError(
-          f'{self.name()} url must be a string: {type(url)} -> "{url}"'
+          f'{self.name()} url must be a string or ComputedObject: '
+          f'{type(url)} -> "{url}"'
       )
 
+    func = apifunction.ApiFunction(self.name())
+    args: dict[str, Any] = {'url': url}
     super().__init__(func, func.promoteArgs(args))
 
   @classmethod
@@ -84,7 +82,7 @@ class Blob(computedobject.ComputedObject):
     return 'Blob'
 
   def string(
-      self, encoding: Optional[_arg_types.String] = None
+      self, encoding: _arg_types.String | None = None
   ) -> ee_string.String:
     """Returns the contents of the blob as a String.