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

ee/daterange.py

@@ -1,7 +1,7 @@
 """A wrapper for DateRanges."""
 from __future__ import annotations
 
-from typing import Any, Dict, Optional, Union
+from typing import Any
 
 from ee import _arg_types
 from ee import apifunction
@@ -29,10 +29,10 @@ class DateRange(computedobject.ComputedObject):
 
   def __init__(
       self,
-      start: Union[_arg_types.Date, _arg_types.DateRange],
-      end: Optional[_arg_types.Date] = None,
+      start: _arg_types.Date | _arg_types.DateRange,
+      end: _arg_types.Date | None = None,
       # pylint: disable-next=invalid-name
-      timeZone: Optional[_arg_types.String] = None,
+      timeZone: _arg_types.String | None = None,
   ):
     """Creates a DateRange wrapper.
 
@@ -58,7 +58,7 @@ class DateRange(computedobject.ComputedObject):
         super().__init__(start.func, start.args, start.varName)
         return
 
-    args: Dict[str, Any] = {'start': start}
+    args: dict[str, Any] = {'start': start}
     if end is not None:
       args['end'] = end
     if timeZone is not None:
@@ -85,7 +85,7 @@ class DateRange(computedobject.ComputedObject):
     return 'DateRange'
 
   def contains(
-      self, other: Union[_arg_types.Date, _arg_types.DateRange]
+      self, other: _arg_types.Date | _arg_types.DateRange
   ) -> computedobject.ComputedObject:
     """Returns true if the given Date or DateRange is within this DateRange.
 
@@ -104,8 +104,8 @@ class DateRange(computedobject.ComputedObject):
     return apifunction.ApiFunction.call_(self.name() + '.end', self)
 
   def intersection(
-      self, other: Union[_arg_types.Date, _arg_types.DateRange]
-  ) -> 'DateRange':
+      self, other: _arg_types.Date | _arg_types.DateRange
+  ) -> DateRange:
     """Returns a DateRange that contains all the timespan of this and other.
 
     Args:
@@ -123,7 +123,7 @@ class DateRange(computedobject.ComputedObject):
     )
 
   def intersects(
-      self, other: Union[_arg_types.Date, _arg_types.DateRange]
+      self, other: _arg_types.Date | _arg_types.DateRange
   ) -> computedobject.ComputedObject:
     """Returns true if the other DateRange has at least one time in common.
 
@@ -160,7 +160,7 @@ class DateRange(computedobject.ComputedObject):
     return apifunction.ApiFunction.call_('DateRange.unbounded')
 
   def union(
-      self, other: Union[_arg_types.Date, _arg_types.DateRange]
+      self, other: _arg_types.Date | _arg_types.DateRange
   ) -> DateRange:
     """Returns a DateRange that contains all points in this and other.
 

ee/deprecation.py

@@ -2,12 +2,13 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 import dataclasses
 import datetime
 import functools
 import inspect
 import json
-from typing import Any, Callable, Dict, Optional
+from typing import Any
 import urllib
 import warnings
 
@@ -15,7 +16,7 @@ _DEPRECATED_OBJECT = 'earthengine-stac/catalog/catalog_deprecated.json'
 _DEPRECATED_ASSETS_URL = f'https://storage.googleapis.com/{_DEPRECATED_OBJECT}'
 
 # Deprecation warnings are per-asset, per-initialization.
-deprecated_assets: Dict[str, DeprecatedAsset] = None
+deprecated_assets: dict[str, DeprecatedAsset] = dict()
 
 
 def Deprecated(message: str):
@@ -36,7 +37,7 @@ def Deprecated(message: str):
     @functools.wraps(func)
     def Wrapper(*args, **kwargs):
       warnings.warn_explicit(
-          '%s() is deprecated: %s' % (func.__name__, message),
+          f'{func.__name__}() is deprecated: {message}',
           category=DeprecationWarning,
           filename=func.__code__.co_filename,
           lineno=func.__code__.co_firstlineno + 1,
@@ -67,14 +68,14 @@ class DeprecatedAsset:
   """Class for keeping track of a single deprecated asset."""
 
   id: str
-  replacement_id: Optional[str]
-  removal_date: Optional[datetime.datetime]
-  learn_more_url: Optional[str]
+  replacement_id: str | None
+  removal_date: datetime.datetime | None
+  learn_more_url: str | None
 
   has_warning_been_issued: bool = False
 
   @classmethod
-  def _ParseDateString(cls, date_str: str) -> Optional[datetime.datetime]:
+  def _ParseDateString(cls, date_str: str) -> datetime.datetime | None:
     try:
       # We can't use `datetime.datetime.fromisoformat` because it's behavior
       # changes by Python version.
@@ -83,12 +84,14 @@ class DeprecatedAsset:
       return None
 
   @classmethod
-  def FromStacLink(cls, stac_link: Dict[str, Any]) -> DeprecatedAsset:
+  def FromStacLink(cls, stac_link: dict[str, Any]) -> DeprecatedAsset:
     removal_date = stac_link.get('gee:removal_date')
     if removal_date is not None:
       removal_date = cls._ParseDateString(removal_date)
+    title = stac_link.get('title')
+    assert isinstance(title, str)
     return DeprecatedAsset(
-        id=stac_link.get('title'),
+        id=title,
         replacement_id=stac_link.get('gee:replacement_id'),
         removal_date=removal_date,
         learn_more_url=stac_link.get('gee:learn_more_url'),
@@ -139,7 +142,7 @@ def InitializeDeprecatedAssets() -> None:
 
 def _InitializeDeprecatedAssetsInternal() -> None:
   global deprecated_assets
-  if deprecated_assets is not None:
+  if deprecated_assets:
     return
   _UnfilterDeprecationWarnings()
 
@@ -153,10 +156,10 @@ def _InitializeDeprecatedAssetsInternal() -> None:
 
 def Reset() -> None:
   global deprecated_assets
-  deprecated_assets = None
+  deprecated_assets = dict()
 
 
-def _FetchDataCatalogStac() -> Dict[str, Any]:
+def _FetchDataCatalogStac() -> dict[str, Any]:
   try:
     response = urllib.request.urlopen(_DEPRECATED_ASSETS_URL).read()
   except (urllib.error.HTTPError, urllib.error.URLError):
@@ -164,7 +167,7 @@ def _FetchDataCatalogStac() -> Dict[str, Any]:
   return json.loads(response)
 
 
-def _GetStringFromObject(obj: Any) -> Optional[str]:
+def _GetStringFromObject(obj: Any) -> str | None:
   if isinstance(obj, str):
     return obj
   return None
@@ -202,6 +205,11 @@ def _IssueAssetDeprecationWarning(asset: DeprecatedAsset) -> None:
       formatted_date = removal_date.strftime('%B %d, %Y').replace(' 0', ' ')
       warning += f' by {formatted_date}'
   warning += '.'
+  if asset.replacement_id:
+    warning = (
+        warning
+        + f'\nThis dataset has been superseded by {asset.replacement_id}\n'
+    )
   if asset.learn_more_url:
     warning = warning + f'\nLearn more: {asset.learn_more_url}\n'
   warnings.warn(warning, category=DeprecationWarning)

ee/deserializer.py

@@ -1,6 +1,7 @@
 """A deserializer that decodes EE object trees from JSON DAGs."""
 
 import json
+from typing import Any
 
 from ee import apifunction
 from ee import computedobject
@@ -12,7 +13,7 @@ from ee import function
 from ee import geometry
 
 
-def fromJSON(json_obj):  # pylint: disable=g-bad-name
+def fromJSON(json_obj: bytes | str) -> Any:  # pylint: disable=g-bad-name
   """Deserialize an object from a JSON string appropriate for API calls.
 
   Args:
@@ -24,7 +25,7 @@ def fromJSON(json_obj):  # pylint: disable=g-bad-name
   return decode(json.loads(json_obj))
 
 
-def decode(json_obj):
+def decode(json_obj: Any) -> Any:
   """Decodes an object previously encoded using the EE API v2 (DAG) format.
 
   Args:
@@ -50,7 +51,8 @@ def decode(json_obj):
   return _decodeValue(json_obj, named_values)
 
 
-def _decodeValue(json_obj, named_values):  # pylint: disable=g-bad-name
+# pylint: disable-next=g-bad-name
+def _decodeValue(json_obj: Any, named_values: dict[str, Any]) -> Any:
   """Decodes an object previously encoded using the EE API v2 (DAG) format.
 
   This uses a provided scope for ValueRef lookup and does not allow the
@@ -74,7 +76,7 @@ def _decodeValue(json_obj, named_values):  # pylint: disable=g-bad-name
 
   # Ensure that we've got a proper object at this point.
   if not isinstance(json_obj, dict):
-    raise ee_exception.EEException('Cannot decode object: ' + json_obj)
+    raise ee_exception.EEException(f'Cannot decode object: {json_obj}')
 
   # Check for explicitly typed values.
   type_name = json_obj['type']
@@ -82,16 +84,16 @@ def _decodeValue(json_obj, named_values):  # pylint: disable=g-bad-name
     if json_obj['value'] in named_values:
       return named_values[json_obj['value']]
     else:
-      raise ee_exception.EEException('Unknown ValueRef: ' + json_obj)
+      raise ee_exception.EEException(f'Unknown ValueRef: {json_obj}')
   elif type_name == 'ArgumentRef':
     var_name = json_obj['value']
     if not isinstance(var_name, str):
-      raise ee_exception.EEException('Invalid variable name: ' + var_name)
-    return customfunction.CustomFunction.variable(None, var_name)  # pylint: disable=protected-access
+      raise ee_exception.EEException(f'Invalid variable name: {var_name}')
+    return customfunction.CustomFunction.variable(None, var_name)
   elif type_name == 'Date':
     microseconds = json_obj['value']
     if not isinstance(microseconds, (float, int)):
-      raise ee_exception.EEException('Invalid date value: ' + microseconds)
+      raise ee_exception.EEException(f'Invalid date value: {microseconds}')
     return ee_date.Date(microseconds / 1e3)
   elif type_name == 'Bytes':
     result = encodable.Encodable()
@@ -105,14 +107,14 @@ def _decodeValue(json_obj, named_values):  # pylint: disable=g-bad-name
     else:
       func = _decodeValue(json_obj['function'], named_values)
     if 'arguments' in json_obj:
-      args = dict((key, _decodeValue(value, named_values))
-                  for (key, value) in json_obj['arguments'].items())
+      args = {key: _decodeValue(value, named_values)
+                  for (key, value) in json_obj['arguments'].items()}
     else:
       args = {}
     return _invocation(func, args)
   elif type_name == 'Dictionary':
-    return dict((key, _decodeValue(value, named_values))
-                for (key, value) in json_obj['value'].items())
+    return {key: _decodeValue(value, named_values)
+                for (key, value) in json_obj['value'].items()}
   elif type_name == 'Function':
     body = _decodeValue(json_obj['body'], named_values)
     signature = {
@@ -129,10 +131,10 @@ def _decodeValue(json_obj, named_values):  # pylint: disable=g-bad-name
   elif type_name == 'CompoundValue':
     raise ee_exception.EEException('Nested CompoundValues are disallowed.')
   else:
-    raise ee_exception.EEException('Unknown encoded object type: ' + type_name)
+    raise ee_exception.EEException(f'Unknown encoded object type: {type_name}')
 
 
-def _invocation(func, args):
+def _invocation(func: Any, args: dict[str, Any]) -> Any:
   """Creates an EE object representing the application of `func` to `args`."""
   if isinstance(func, function.Function):
     return func.apply(args)
@@ -148,10 +150,10 @@ def _invocation(func, args):
         'returns': 'ComputedObject'
     }
     return function.SecondOrderFunction(func, signature).apply(args)
-  raise ee_exception.EEException('Invalid function value: %s' % func)
+  raise ee_exception.EEException(f'Invalid function value: {func}')
 
 
-def fromCloudApiJSON(json_obj):  # pylint: disable=g-bad-name
+def fromCloudApiJSON(json_obj: str | bytes) -> Any:  # pylint: disable=g-bad-name
   """Deserializes an object from the JSON string used in Cloud API calls.
 
   Args:
@@ -163,7 +165,8 @@ def fromCloudApiJSON(json_obj):  # pylint: disable=g-bad-name
   return decodeCloudApi(json.loads(json_obj))
 
 
-def decodeCloudApi(json_obj):  # pylint: disable=g-bad-name
+# pylint: disable-next=g-bad-name
+def decodeCloudApi(json_obj: dict[str, Any]) -> Any:
   """Decodes an object previously encoded using the EE Cloud API format.
 
   Args:
@@ -177,7 +180,7 @@ def decodeCloudApi(json_obj):  # pylint: disable=g-bad-name
   def lookup(reference, kind):
     if reference not in decoded:
       if reference not in json_obj['values']:
-        raise ee_exception.EEException('Cannot find %s %s' % (reference, kind))
+        raise ee_exception.EEException(f'Cannot find {reference} {kind}')
       decoded[reference] = decode_node(json_obj['values'][reference])
     return decoded[reference]
 
@@ -206,14 +209,16 @@ def decodeCloudApi(json_obj):  # pylint: disable=g-bad-name
       return lookup(node['valueReference'], 'reference')
     return None
 
-  def decode_function_definition(defined):
+  def decode_function_definition(
+      defined: dict[str, Any],
+  ) -> customfunction.CustomFunction:
     body = lookup(defined['body'], 'function body')
     signature_args = [{'name': name, 'type': 'Object', 'optional': False}
                       for name in defined['argumentNames']]
     signature = {'args': signature_args, 'name': '', 'returns': 'Object'}
     return customfunction.CustomFunction(signature, lambda *args: body)
 
-  def decode_function_invocation(invoked):
+  def decode_function_invocation(invoked: dict[str, Any]) -> Any:
     if 'functionReference' in invoked:
       func = lookup(invoked['functionReference'], 'function')
     else:

ee/dictionary.py

@@ -1,7 +1,7 @@
 """A wrapper for dictionaries."""
 from __future__ import annotations
 
-from typing import Any, Dict, Optional, Union
+from typing import Any, Union
 
 from ee import _arg_types
 from ee import _utils
@@ -26,14 +26,14 @@ _StringListType = Union[Any, computedobject.ComputedObject]
 class Dictionary(computedobject.ComputedObject):
   """An object to represent dictionaries."""
 
-  _dictionary: Optional[Dict[Any, Any]]
+  _dictionary: dict[Any, Any] | None
 
   _initialized = False
 
   # Tell pytype to not complain about dynamic attributes.
   _HAS_DYNAMIC_ATTRIBUTES = True
 
-  def __init__(self, arg: Optional[_arg_types.Dictionary] = None):
+  def __init__(self, arg: _arg_types.Dictionary | None = None):
     """Construct a dictionary.
 
     Args:
@@ -91,7 +91,7 @@ class Dictionary(computedobject.ComputedObject):
   def combine(
       self,
       second: _arg_types.Dictionary,
-      overwrite: Optional[_arg_types.Bool] = None,
+      overwrite: _arg_types.Bool | None = None,
   ) -> Dictionary:
     """Combines two dictionaries.
 
@@ -140,7 +140,7 @@ class Dictionary(computedobject.ComputedObject):
       self,
       key: _EeKeyType,
       # pylint: disable-next=invalid-name
-      defaultValue: Optional[_arg_types.Any] = None,
+      defaultValue: _arg_types.Any | None = None,
   ) -> computedobject.ComputedObject:
     """Extracts a named value from a dictionary.
 
@@ -237,7 +237,7 @@ class Dictionary(computedobject.ComputedObject):
       self,
       selectors: _arg_types.Any,
       # pylint: disable-next=invalid-name
-      ignoreMissing: Optional[_arg_types.Bool] = None,
+      ignoreMissing: _arg_types.Bool | None = None,
   ) -> Dictionary:
     """Returns a dictionary with the specified keys removed.
 
@@ -278,7 +278,7 @@ class Dictionary(computedobject.ComputedObject):
       self,
       selectors: _arg_types.Any,
       # pylint: disable-next=invalid-name
-      ignoreMissing: Optional[_arg_types.Bool] = None,
+      ignoreMissing: _arg_types.Bool | None = None,
   ) -> Dictionary:
     """Returns a dictionary with only the specified keys.
 
@@ -315,8 +315,8 @@ class Dictionary(computedobject.ComputedObject):
 
   def toArray(
       self,
-      keys: Optional[_EeKeyListType] = None,
-      axis: Optional[_arg_types.Integer] = None,
+      keys: _EeKeyListType | None = None,
+      axis: _arg_types.Integer | None = None,
   ) -> ee_array.Array:
     """Returns numeric values of a dictionary as an array.
 
@@ -335,7 +335,7 @@ class Dictionary(computedobject.ComputedObject):
         self.name() + '.toArray', self, keys, axis
     )
 
-  def toImage(self, names: Optional[_arg_types.Any] = None) -> image.Image:
+  def toImage(self, names: _arg_types.Any | None = None) -> image.Image:
     """Creates an image of constants from values in a dictionary.
 
     The bands of the image are ordered and named according to the names
@@ -351,7 +351,7 @@ class Dictionary(computedobject.ComputedObject):
 
     return apifunction.ApiFunction.call_(self.name() + '.toImage', self, names)
 
-  def values(self, keys: Optional[_EeKeyListType] = None) -> ee_list.List:
+  def values(self, keys: _EeKeyListType | None = None) -> ee_list.List:
     """Returns the values of a dictionary as a list.
 
     If no keys are specified, all values are returned in the natural ordering of

ee/ee_array.py

@@ -1,7 +1,7 @@
 """A wrapper for Arrays."""
 from __future__ import annotations
 
-from typing import Any, Dict, Optional
+from typing import Any
 
 from ee import _arg_types
 from ee import apifunction
@@ -37,7 +37,7 @@ class Array(computedobject.ComputedObject):
       self,
       values: _arg_types.Array,
       # pylint: disable-next=invalid-name
-      pixelType: Optional[_arg_types.String] = None,
+      pixelType: _arg_types.String | None = None,
   ):
     """Creates an Array wrapper.
 
@@ -60,7 +60,7 @@ class Array(computedobject.ComputedObject):
         super().__init__(values.func, values.args, values.varName)
         return
 
-    args: Dict[str, Any] = {'values': values}
+    args: dict[str, Any] = {'values': values}
     if pixelType is not None:
       args['pixelType'] = pixelType
 
@@ -92,7 +92,7 @@ class Array(computedobject.ComputedObject):
   def accum(
       self,
       axis: _arg_types.Integer,
-      reducer: Optional[_arg_types.Reducer] = None,
+      reducer: _arg_types.Reducer | None = None,
   ) -> Array:
     """Accumulates elements of an array along the given axis.
 
@@ -189,6 +189,8 @@ class Array(computedobject.ComputedObject):
 
     return apifunction.ApiFunction.call_(self.name() + '.bitCount', self)
 
+  @staticmethod
+  # pylint: disable-next=redefined-builtin
   def bitsToArray(input: _arg_types.Integer) -> Array:
     """Returns an Array from the bits of an integer.
 
@@ -261,7 +263,7 @@ class Array(computedobject.ComputedObject):
 
   @staticmethod
   def cat(
-      arrays: _arg_types.List, axis: Optional[_arg_types.Integer] = None
+      arrays: _arg_types.List, axis: _arg_types.Integer | None = None
   ) -> Array:
     """Returns an Array that is the concatenation of the given arrays.
 
@@ -748,8 +750,8 @@ class Array(computedobject.ComputedObject):
 
   def matrixTranspose(
       self,
-      axis1: Optional[_arg_types.Integer] = None,
-      axis2: Optional[_arg_types.Integer] = None,
+      axis1: _arg_types.Integer | None = None,
+      axis2: _arg_types.Integer | None = None,
   ) -> Array:
     """Transposes two dimensions of an array.
 
@@ -843,7 +845,7 @@ class Array(computedobject.ComputedObject):
     return apifunction.ApiFunction.call_(self.name() + '.or', self, right)
 
   def pad(
-      self, lengths: _arg_types.Any, pad: Optional[_arg_types.Number] = None
+      self, lengths: _arg_types.Any, pad: _arg_types.Number | None = None
   ) -> Array:
     """Pad an array to a given length.
 
@@ -896,7 +898,7 @@ class Array(computedobject.ComputedObject):
       reducer: _arg_types.Reducer,
       axes: _arg_types.Any,
       # pylint: disable-next=invalid-name
-      fieldAxis: Optional[_arg_types.Integer] = None,
+      fieldAxis: _arg_types.Integer | None = None,
   ) -> Array:
     """Returns the result of applying the reducer on the array.
 
@@ -934,8 +936,8 @@ class Array(computedobject.ComputedObject):
 
   def repeat(
       self,
-      axis: Optional[_arg_types.Integer] = None,
-      copies: Optional[_arg_types.Integer] = None,
+      axis: _arg_types.Integer | None = None,
+      copies: _arg_types.Integer | None = None,
   ) -> Array:
     """Repeats the array along the given axis.
 
@@ -1019,10 +1021,10 @@ class Array(computedobject.ComputedObject):
 
   def slice(
       self,
-      axis: Optional[_arg_types.Integer] = None,
-      start: Optional[_arg_types.Integer] = None,
-      end: Optional[_arg_types.Integer] = None,
-      step: Optional[_arg_types.Integer] = None,
+      axis: _arg_types.Integer | None = None,
+      start: _arg_types.Integer | None = None,
+      end: _arg_types.Integer | None = None,
+      step: _arg_types.Integer | None = None,
   ) -> Array:
     """Returns the result of slicing the array along the given axis.
 
@@ -1041,7 +1043,7 @@ class Array(computedobject.ComputedObject):
       start: The coordinate of the first slice (inclusive) along 'axis'.
         Negative numbers are used to position the start of slicing relative to
         the end of the array, where -1 starts at the last position on the axis,
-        -2 starts at the next to last position, etc.  Defaults to 0.
+        -2 starts at the next to last position, etc. Defaults to 0.
       end: The coordinate (exclusive) at which to stop taking slices. By default
         this will be the length of the given axis. Negative numbers are used to
         position the end of slicing relative to the end of the array, where -1
@@ -1049,7 +1051,7 @@ class Array(computedobject.ComputedObject):
         etc.
       step: The separation between slices along 'axis'; a slice will be taken at
         each whole multiple of 'step' from 'start' (inclusive) to 'end'
-        (exclusive). Must be positive.  Defaults to 1.
+        (exclusive). Must be positive. Defaults to 1.
 
     Returns:
       An ee.Array.
@@ -1059,7 +1061,7 @@ class Array(computedobject.ComputedObject):
         self.name() + '.slice', self, axis, start, end, step
     )
 
-  def sort(self, keys: Optional[_arg_types.Any] = None) -> Array:
+  def sort(self, keys: _arg_types.Any | None = None) -> Array:
     """Sorts elements of the array along one axis.
 
     Args:
@@ -1172,8 +1174,8 @@ class Array(computedobject.ComputedObject):
 
   def transpose(
       self,
-      axis1: Optional[_arg_types.Integer] = None,
-      axis2: Optional[_arg_types.Integer] = None,
+      axis1: _arg_types.Integer | None = None,
+      axis2: _arg_types.Integer | None = None,
   ) -> Array:
     """Transposes two dimensions of an array.