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

ee/collection.py

@@ -5,8 +5,9 @@ This class is never intended to be instantiated by the user.
 
 from __future__ import annotations
 
+from collections.abc import Callable
 import datetime
-from typing import Any, Callable, Dict, Optional, Type, Union
+from typing import Any, Generic, TypeVar
 
 from ee import _arg_types
 from ee import _utils
@@ -26,8 +27,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
@@ -37,8 +44,8 @@ class Collection(element.Element):
   def __init__(
       self,
       func: function.Function,
-      args: Dict[str, Any],
-      varName: Optional[str] = None,  # pylint: disable=invalid-name
+      args: dict[str, Any],
+      varName: str | None = None,  # pylint: disable=invalid-name
   ):
     """Constructs a collection by initializing its ComputedObject."""
     super().__init__(func, args, varName)
@@ -198,7 +205,7 @@ class Collection(element.Element):
 
   # pylint: disable-next=redefined-builtin
   def aggregate_product(self, property: _arg_types.String) -> ee_number.Number:
-    """Returns the product of the values ofthe selected property.
+    """Returns the product of the values of the selected property.
 
     Aggregates over a given property of the objects in a collection, calculating
     the product of the values of the selected property.
@@ -320,8 +327,8 @@ class Collection(element.Element):
   def bounds(
       self,
       # pylint: disable-next=invalid-name
-      maxError: Optional[_arg_types.ErrorMargin] = None,
-      proj: Optional[_arg_types.Projection] = None,
+      maxError: _arg_types.ErrorMargin | None = None,
+      proj: _arg_types.Projection | None = None,
   ) -> ee_geometry.Geometry:
     """Returns the bounding rectangle of the geometry.
 
@@ -339,8 +346,8 @@ class Collection(element.Element):
   def distance(
       self,
       # pylint: disable=invalid-name
-      searchRadius: Optional[_arg_types.Number] = None,
-      maxError: Optional[_arg_types.Number] = None,
+      searchRadius: _arg_types.Number | None = None,
+      maxError: _arg_types.Number | None = None,
       # pylint: enable=invalid-name
   ) -> image.Image:
     """Returns a distance image for the collection.
@@ -368,7 +375,7 @@ class Collection(element.Element):
     )
 
   def distinct(
-      self, properties: Union[_arg_types.String, _arg_types.List]
+      self, properties: _arg_types.String | _arg_types.List
   ) -> featurecollection.FeatureCollection:
     """Returns a collection with duplicates removed.
 
@@ -389,8 +396,8 @@ class Collection(element.Element):
       self,
       color: _arg_types.String,
       # pylint: disable=invalid-name
-      pointRadius: Optional[_arg_types.Integer] = None,
-      strokeWidth: Optional[_arg_types.Integer] = None,
+      pointRadius: _arg_types.Integer | None = None,
+      strokeWidth: _arg_types.Integer | None = None,
       # pylint: enable=invalid-name
   ) -> image.Image:
     """Returns a painted image of a vector collection for visualization.
@@ -409,7 +416,7 @@ class Collection(element.Element):
     )
 
   @staticmethod
-  def elementType() -> Type[element.Element]:
+  def elementType() -> type[element.Element]:
     """Returns the type of the collection's elements."""
     return element.Element
 
@@ -417,7 +424,7 @@ class Collection(element.Element):
       self,
       actual: _arg_types.String,
       predicted: _arg_types.String,
-      order: Optional[_arg_types.List] = None,
+      order: _arg_types.List | None = None,
   ) -> confusionmatrix.ConfusionMatrix:
     """Returns a 2D error matrix for a collection.
 
@@ -442,7 +449,7 @@ class Collection(element.Element):
         'Collection.errorMatrix', self, actual, predicted, order
     )
 
-  def filter(self, new_filter: Union[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 +466,8 @@ class Collection(element.Element):
 
   @deprecation.CanUseDeprecated
   def filterMetadata(
-      self, name: str, operator: str, value: Union[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 +475,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 +487,13 @@ class Collection(element.Element):
     return self.filter(ee_filter.Filter.metadata_(name, operator, value))
 
   def filterBounds(
-      self, geometry: Union[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 +517,10 @@ class Collection(element.Element):
   # TODO(user): Any --> DateRange
   @_utils.accept_opt_prefix('opt_end')
   def filterDate(
-      self,
-      start: Union[datetime.datetime, ee_date.Date, int, str, Any],
-      end: Optional[
-          Union[datetime.datetime, ee_date.Date, int, str, Any]
-      ] = None,
-  ) -> Any:
+      self: T,
+      start: datetime.datetime | ee_date.Date | int | str | 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 +539,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)
@@ -542,7 +552,7 @@ class Collection(element.Element):
   def geometry(
       self,
       # pylint: disable-next=invalid-name
-      maxError: Optional[_arg_types.ErrorMargin] = None,
+      maxError: _arg_types.ErrorMargin | None = None,
   ) -> ee_geometry.Geometry:
     """Returns the geometry of a collection.
 
@@ -563,7 +573,7 @@ class Collection(element.Element):
     )
 
   # pylint: disable-next=useless-parent-delegation
-  def getInfo(self) -> Optional[Any]:
+  def getInfo(self) -> Any | None:
     """Returns all the known information about this collection.
 
     This function makes a REST call to to retrieve all the known information
@@ -579,7 +589,7 @@ class Collection(element.Element):
     return super().getInfo()
 
   def iterate(
-      self, algorithm: Callable[[Any, Any], Any], first: Optional[Any] = None
+      self, algorithm: Callable[[Any, Any], Any], first: Any | None = None
   ) -> Any:
     """Iterates over a collection with an algorithm.
 
@@ -610,8 +620,8 @@ class Collection(element.Element):
   def limit(
       self,
       maximum: int,
-      prop: Optional[str] = None,
-      ascending: Optional[bool] = None,
+      prop: str | None = None,
+      ascending: bool | None = None,
   ) -> Collection:
     """Limit a collection to the specified number of elements.
 
@@ -639,9 +649,9 @@ class Collection(element.Element):
   def loadTable(
       # pylint: disable=invalid-name
       tableId: _arg_types.String,
-      geometryColumn: Optional[_arg_types.String] = None,
+      geometryColumn: _arg_types.String | None = None,
       # pylint: enable=invalid-name
-      version: Optional[_arg_types.Integer] = None,
+      version: _arg_types.Integer | None = None,
   ) -> featurecollection.FeatureCollection:
     """Returns a Collection of features from a specified table.
 
@@ -660,10 +670,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: Optional[bool] = None,  # pylint: disable=invalid-name
-  ) -> Any:
+      dropNulls: bool | None = None,  # pylint: disable=invalid-name
+  ) -> T:
     """Maps an algorithm over a collection.
 
     Args:
@@ -714,11 +724,11 @@ class Collection(element.Element):
   def randomColumn(
       self,
       # pylint: disable-next=invalid-name
-      columnName: Optional[_arg_types.String] = None,
-      seed: Optional[_arg_types.Integer] = None,
-      distribution: Optional[_arg_types.String] = None,
+      columnName: _arg_types.String | None = None,
+      seed: _arg_types.Integer | None = None,
+      distribution: _arg_types.String | None = None,
       # pylint: disable-next=invalid-name
-      rowKeys: Optional[_arg_types.List] = None,
+      rowKeys: _arg_types.List | None = None,
   ) -> featurecollection.FeatureCollection:
     """Returns a collection with a random column added to each feature.
 
@@ -747,7 +757,7 @@ class Collection(element.Element):
       reducer: _arg_types.Reducer,
       selectors: _arg_types.List,
       # pylint: disable=invalid-name
-      weightSelectors: Optional[_arg_types.List] = None,
+      weightSelectors: _arg_types.List | None = None,
   ) -> dictionary.Dictionary:
     """Returns a dictionary of results, keyed with the output names.
 
@@ -822,12 +832,12 @@ class Collection(element.Element):
 
   # TODO(user): Make ascending default to True
   @_utils.accept_opt_prefix('opt_ascending')
-  def sort(self, prop: str, ascending: Optional[bool] = 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:
@@ -841,19 +851,19 @@ class Collection(element.Element):
 
   def style(
       self,
-      color: Optional[_arg_types.String] = None,
+      color: _arg_types.String | None = None,
       # pylint: disable=invalid-name
-      pointSize: Optional[_arg_types.Integer] = None,
-      pointShape: Optional[_arg_types.String] = None,
+      pointSize: _arg_types.Integer | None = None,
+      pointShape: _arg_types.String | None = None,
       # pylint: enable=invalid-name
-      width: Optional[_arg_types.Number] = None,
+      width: _arg_types.Number | None = None,
       # pylint: disable=invalid-name
-      fillColor: Optional[_arg_types.String] = None,
-      styleProperty: Optional[_arg_types.String] = None,
+      fillColor: _arg_types.String | None = None,
+      styleProperty: _arg_types.String | None = None,
       # pylint: enable=invalid-name
-      neighborhood: Optional[_arg_types.Integer] = None,
+      neighborhood: _arg_types.Integer | None = None,
       # pylint: disable-next=invalid-name
-      lineType: Optional[_arg_types.String] = None,
+      lineType: _arg_types.String | None = None,
   ) -> image.Image:
     """Draw a vector collection for visualization using a simple style language.
 
@@ -900,7 +910,7 @@ class Collection(element.Element):
   def toList(
       self,
       count: _arg_types.Integer,
-      offset: Optional[_arg_types.Integer] = None,
+      offset: _arg_types.Integer | None = None,
   ) -> ee_list.List:
     """Returns the elements of a collection as a list.
 
@@ -918,7 +928,7 @@ class Collection(element.Element):
   def union(
       self,
       # pylint: disable-next=invalid-name
-      maxError: Optional[_arg_types.ErrorMargin] = None,
+      maxError: _arg_types.ErrorMargin | None = None,
   ) -> featurecollection.FeatureCollection:
     """Returns a collection containing a single feature with a unioned geometry.
 

ee/computedobject.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from typing import Any, Callable, Dict, Optional
+from collections.abc import Callable
+from typing import Any
 
 from ee import _utils
 from ee import data
@@ -38,18 +39,18 @@ 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.
   """
-  func: Optional[Any]
-  args: Optional[Dict[str, Any]]
-  varName: Optional[str]  # pylint: disable=g-bad-name
+  func: Any | None
+  args: dict[str, Any] | None
+  varName: str | None  # pylint: disable=g-bad-name
 
   # Tell pytype not to worry about dynamic attributes.
   _HAS_DYNAMIC_ATTRIBUTES: bool = True
@@ -60,9 +61,9 @@ class ComputedObject(encodable.Encodable, metaclass=ComputedObjectMetaclass):
   @_utils.accept_opt_prefix('opt_varName')
   def __init__(
       self,
-      func: Optional[Any],
-      args: Optional[Dict[str, Any]],
-      varName: Optional[str] = None,  # pylint: disable=g-bad-name
+      func: Any | None,
+      args: dict[str, Any] | None,
+      varName: str | None = None,  # pylint: disable=g-bad-name
   ):
     """Creates a computed object.
 
@@ -98,7 +99,7 @@ class ComputedObject(encodable.Encodable, metaclass=ComputedObjectMetaclass):
     return hash(ComputedObject.freeze(self.__dict__))
 
   # pylint: disable-next=useless-parent-delegation
-  def getInfo(self) -> Optional[Any]:
+  def getInfo(self) -> Any | None:
     """Fetch and return information about this object.
 
     Returns:
@@ -106,7 +107,7 @@ class ComputedObject(encodable.Encodable, metaclass=ComputedObjectMetaclass):
     """
     return data.computeValue(self)
 
-  def encode(self, encoder: Optional[Callable[..., Any]]) -> Dict[str, Any]:
+  def encode(self, encoder: Callable[..., Any] | None) -> dict[str, Any]:
     """Encodes the object in a format compatible with Serializer."""
     if self.isVariable():
       return {
@@ -135,7 +136,7 @@ class ComputedObject(encodable.Encodable, metaclass=ComputedObjectMetaclass):
           key: func
       }
 
-  def encode_cloud_value(self, encoder: Any) -> Dict[str, Any]:
+  def encode_cloud_value(self, encoder: Any) -> dict[str, Any]:
     if self.isVariable():
       ref = self.varName
       if ref is None and isinstance(
@@ -160,7 +161,7 @@ class ComputedObject(encodable.Encodable, metaclass=ComputedObjectMetaclass):
         invocation = self.func.encode_cloud_invocation(encoder)
 
       # Encode all arguments recursively.
-      encoded_args: Dict[str, Any] = {}
+      encoded_args: dict[str, Any] = {}
       for name in sorted(self.args):
         value = self.args[name]
         if value is not None:
@@ -184,7 +185,7 @@ class ComputedObject(encodable.Encodable, metaclass=ComputedObjectMetaclass):
 
   def __str__(self) -> str:
     """Writes out the object in a human-readable form."""
-    return 'ee.%s(%s)' % (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."""
@@ -233,9 +234,11 @@ class ComputedObject(encodable.Encodable, metaclass=ComputedObjectMetaclass):
       return obj
     else:
       result = cls.__new__(cls)  # pylint: disable=no-value-for-parameter
+      # pylint: disable=attribute-error
       result.func = obj.func
       result.args = obj.args
       result.varName = obj.varName
+      # pylint: enable=attribute-error
       return result
 
   @staticmethod

ee/confusionmatrix.py

@@ -1,7 +1,7 @@
 """A wrapper for ConfusionMatrices."""
 from __future__ import annotations
 
-from typing import Any, Dict, Optional, Union
+from typing import Any
 
 from ee import _arg_types
 from ee import apifunction
@@ -30,12 +30,12 @@ class ConfusionMatrix(computedobject.ComputedObject):
 
   def __init__(
       self,
-      array: Union[
-          ee_array.Array,
-          _arg_types.ConfusionMatrix,
-          computedobject.ComputedObject,
-      ],
-      order: Optional[_arg_types.List] = None,
+      array: (
+          ee_array.Array |
+          _arg_types.ConfusionMatrix |
+          computedobject.ComputedObject
+      ),
+      order: _arg_types.List | None = None,
   ):
     """Creates a ConfusionMatrix wrapper.
 
@@ -57,7 +57,7 @@ class ConfusionMatrix(computedobject.ComputedObject):
         super().__init__(array.func, array.args, array.varName)
         return
 
-    args: Dict[str, Any] = {'array': array}
+    args: dict[str, Any] = {'array': array}
     if order is not None:
       args['order'] = order
 
@@ -102,7 +102,7 @@ class ConfusionMatrix(computedobject.ComputedObject):
         self.name() + '.consumersAccuracy', self
     )
 
-  def fscore(self, beta: Optional[_arg_types.Number] = None) -> ee_array.Array:
+  def fscore(self, beta: _arg_types.Number | None = None) -> ee_array.Array:
     """Returns the F-beta score for the confusion matrix.
 
     Args:

ee/customfunction.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from typing import Any, Callable, Dict, Optional
+from collections.abc import Callable
+from typing import Any
 
 from ee import computedobject
 from ee import ee_exception
@@ -20,9 +21,9 @@ from ee import serializer
 class CustomFunction(function.Function, encodable.Encodable):
   """An object representing a custom EE Function."""
   _body: Any
-  _signature: Dict[str, Any]
+  _signature: dict[str, Any]
 
-  def __init__(self, signature: Dict[str, Any], body: Any):
+  def __init__(self, signature: dict[str, Any], body: Any):
     """Creates a function defined by a given expression with unbound variables.
 
     The expression is created by evaluating the given function
@@ -47,14 +48,14 @@ class CustomFunction(function.Function, encodable.Encodable):
     # The expression to evaluate.
     self._body = body(*variables)
 
-  def encode(self, encoder: Callable[[Any], Any]) -> Dict[str, Any]:
+  def encode(self, encoder: Callable[[Any], Any]) -> dict[str, Any]:
     return {
         'type': 'Function',
         'argumentNames': [x['name'] for x in self._signature['args']],
         'body': encoder(self._body)
     }
 
-  def encode_cloud_value(self, encoder: Callable[[Any], Any]) -> Dict[str, Any]:
+  def encode_cloud_value(self, encoder: Callable[[Any], Any]) -> dict[str, Any]:
     return {
         'functionDefinitionValue': {
             'argumentNames': [x['name'] for x in self._signature['args']],
@@ -62,20 +63,20 @@ class CustomFunction(function.Function, encodable.Encodable):
         }
     }
 
-  def encode_invocation(self, encoder: Callable[[Any], Any]) -> Dict[str, Any]:
+  def encode_invocation(self, encoder: Callable[[Any], Any]) -> dict[str, Any]:
     return self.encode(encoder)
 
   def encode_cloud_invocation(
       self, encoder: Callable[[Any], Any]
-  ) -> Dict[str, Any]:
+  ) -> dict[str, Any]:
     return {'functionReference': encoder(self)}
 
-  def getSignature(self) -> Dict[str, Any]:
+  def getSignature(self) -> dict[str, Any]:
     """Returns a description of the interface provided by this function."""
     return self._signature
 
   @staticmethod
-  def variable(type_name: Optional[str], name: str) -> Any:
+  def variable(type_name: str | None, name: str) -> Any:
     """Returns a placeholder variable with a given name and EE type.
 
     Args:
@@ -171,19 +172,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(