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

ee/model.py

@@ -1,7 +1,5 @@
 """A wrapper for Models."""
 
-from typing import Optional
-
 from ee import _arg_types
 from ee import apifunction
 from ee import computedobject
@@ -66,26 +64,26 @@ class Model(computedobject.ComputedObject):
   @deprecation.Deprecated('Migrate to Vertex AI')
   def fromAiPlatformPredictor(
       # pylint: disable=invalid-name
-      projectName: Optional[_arg_types.Any] = None,
-      projectId: Optional[_arg_types.String] = None,
-      modelName: Optional[_arg_types.String] = None,
+      projectName: _arg_types.Any | None = None,
+      projectId: _arg_types.String | None = None,
+      modelName: _arg_types.String | None = None,
       # pylint: enable=invalid-name
-      version: Optional[_arg_types.String] = None,
-      region: Optional[_arg_types.String] = None,
+      version: _arg_types.String | None = None,
+      region: _arg_types.String | None = None,
       # pylint: disable=invalid-name
-      inputProperties: Optional[_arg_types.List] = None,
-      inputTypeOverride: Optional[_arg_types.Dictionary] = None,
-      inputShapes: Optional[_arg_types.Dictionary] = None,
+      inputProperties: _arg_types.List | None = None,
+      inputTypeOverride: _arg_types.Dictionary | None = None,
+      inputShapes: _arg_types.Dictionary | None = None,
       # pylint: enable=invalid-name
-      proj: Optional[_arg_types.Projection] = None,
+      proj: _arg_types.Projection | None = None,
       # pylint: disable=invalid-name
-      fixInputProj: Optional[_arg_types.Bool] = None,
-      inputTileSize: Optional[_arg_types.List] = None,
-      inputOverlapSize: Optional[_arg_types.List] = None,
-      outputTileSize: Optional[_arg_types.List] = None,
-      outputBands: Optional[_arg_types.Dictionary] = None,
-      outputProperties: Optional[_arg_types.Dictionary] = None,
-      outputMultiplier: Optional[_arg_types.Number] = None,
+      fixInputProj: _arg_types.Bool | None = None,
+      inputTileSize: _arg_types.List | None = None,
+      inputOverlapSize: _arg_types.List | None = None,
+      outputTileSize: _arg_types.List | None = None,
+      outputBands: _arg_types.Dictionary | None = None,
+      outputProperties: _arg_types.Dictionary | None = None,
+      outputMultiplier: _arg_types.Number | None = None,
       # pylint: enable=invalid-name
   ) -> 'Model':
     """Returns an ee.Model from a description of an AI Platform prediction model.
@@ -168,21 +166,21 @@ class Model(computedobject.ComputedObject):
   def fromVertexAi(
       endpoint: _arg_types.String,
       # pylint: disable=invalid-name
-      inputProperties: Optional[_arg_types.List] = None,
-      inputTypeOverride: Optional[_arg_types.Dictionary] = None,
-      inputShapes: Optional[_arg_types.Dictionary] = None,
+      inputProperties: _arg_types.List | None = None,
+      inputTypeOverride: _arg_types.Dictionary | None = None,
+      inputShapes: _arg_types.Dictionary | None = None,
       # pylint: enable=invalid-name
-      proj: Optional[_arg_types.Projection] = None,
+      proj: _arg_types.Projection | None = None,
       # pylint: disable=invalid-name
-      fixInputProj: Optional[_arg_types.Bool] = None,
-      inputTileSize: Optional[_arg_types.List] = None,
-      inputOverlapSize: Optional[_arg_types.List] = None,
-      outputTileSize: Optional[_arg_types.List] = None,
-      outputBands: Optional[_arg_types.Dictionary] = None,
-      outputProperties: Optional[_arg_types.Dictionary] = None,
-      outputMultiplier: Optional[_arg_types.Number] = None,
-      maxPayloadBytes: Optional[_arg_types.Integer] = None,
-      payloadFormat: Optional[_arg_types.String] = None,
+      fixInputProj: _arg_types.Bool | None = None,
+      inputTileSize: _arg_types.List | None = None,
+      inputOverlapSize: _arg_types.List | None = None,
+      outputTileSize: _arg_types.List | None = None,
+      outputBands: _arg_types.Dictionary | None = None,
+      outputProperties: _arg_types.Dictionary | None = None,
+      outputMultiplier: _arg_types.Number | None = None,
+      maxPayloadBytes: _arg_types.Integer | None = None,
+      payloadFormat: _arg_types.String | None = None,
       # pylint: enable=invalid-name
   ) -> 'Model':
     """Returns an ee.Model from a description of a Vertex AI model endpoint.

ee/oauth.py

@@ -9,6 +9,7 @@ Typical use-case consists of:
 """
 
 import base64
+from collections.abc import Sequence
 import errno
 import hashlib
 import http.server
@@ -17,7 +18,7 @@ import os
 import shutil
 import subprocess
 import sys
-from typing import Any, Dict, Optional, Sequence, Union
+from typing import Any
 import urllib.error
 import urllib.parse
 import urllib.request
@@ -87,7 +88,7 @@ def get_credentials_path() -> str:
   return cred_path
 
 
-def get_credentials_arguments() -> Dict[str, Any]:
+def get_credentials_arguments() -> dict[str, Any]:
   with open(get_credentials_path()) as creds:
     stored = json.load(creds)
     args = {}
@@ -100,13 +101,13 @@ def get_credentials_arguments() -> Dict[str, Any]:
     return args
 
 
-def is_sdk_credentials(credentials: Optional[Any]) -> bool:
+def is_sdk_credentials(credentials: Any | None) -> bool:
   return is_sdk_project(project_number_from_credentials(credentials))
 
 
 def project_number_from_credentials(
-    credentials: Optional[Any],
-) -> Optional[str]:
+    credentials: Any | None,
+) -> str | None:
   client_id = credentials and getattr(credentials, 'client_id', None)
   return _project_number_from_client_id(client_id)
 
@@ -115,7 +116,7 @@ def is_sdk_project(project: str) -> bool:
   return project in SDK_PROJECTS
 
 
-def get_appdefault_project() -> Optional[str]:
+def get_appdefault_project() -> str | None:
   try:
     adc_path = _cloud_sdk.get_application_default_credentials_path()
     with open(adc_path) as adc_json:
@@ -133,7 +134,7 @@ def _valid_credentials_exist() -> bool:
     return False
 
 
-def is_valid_credentials(credentials: Optional[Any]) -> bool:
+def is_valid_credentials(credentials: Any | None) -> bool:
   if credentials is None:
     return False
   try:
@@ -145,8 +146,8 @@ def is_valid_credentials(credentials: Optional[Any]) -> bool:
 
 def get_authorization_url(
     code_challenge: str,
-    scopes: Optional[Sequence[str]] = None,
-    redirect_uri: Optional[str] = None,
+    scopes: Sequence[str] | None = None,
+    redirect_uri: str | None = None,
 ) -> str:
   """Returns a URL to generate an auth code."""
 
@@ -163,9 +164,9 @@ def get_authorization_url(
 def request_token(
     auth_code: str,
     code_verifier: str,
-    client_id: Optional[str] = None,
-    client_secret: Optional[str] = None,
-    redirect_uri: Optional[str] = None,
+    client_id: str | None = None,
+    client_secret: str | None = None,
+    redirect_uri: str | None = None,
 ) -> str:
   """Uses authorization code to request tokens."""
 
@@ -184,14 +185,14 @@ def request_token(
         urllib.parse.urlencode(request_args).encode()).read().decode()
   except urllib.error.HTTPError as e:
     # pylint:disable=broad-exception-raised,raise-missing-from
-    raise Exception('Problem requesting tokens. Please try again.  %s %s' %
+    raise Exception('Problem requesting tokens. Please try again. %s %s' %
                     (e, e.read()))
     # pylint:enable=broad-exception-raised,raise-missing-from
 
   return json.loads(response)['refresh_token']
 
 
-def write_private_json(json_path: str, info_dict: Dict[str, Any]) -> None:
+def write_private_json(json_path: str, info_dict: dict[str, Any]) -> None:
   """Attempts to write the passed token to the given user directory."""
 
   dirname = os.path.dirname(json_path)
@@ -200,7 +201,7 @@ def write_private_json(json_path: str, info_dict: Dict[str, Any]) -> None:
   except OSError as e:
     if e.errno != errno.EEXIST:
       # pylint:disable=broad-exception-raised,raise-missing-from
-      raise Exception('Error creating directory %s: %s' % (dirname, e))
+      raise Exception(f'Error creating directory {dirname}: {e}')
       # pylint:enable=broad-exception-raised,raise-missing-from
 
   file_content = json.dumps(info_dict)
@@ -225,7 +226,7 @@ def _in_jupyter_shell() -> bool:
   """Tests if the code is being executed within Jupyter."""
   try:
     import ipykernel.zmqshell
-    return isinstance(IPython.get_ipython(),
+    return isinstance(IPython.get_ipython(),  # pylint: disable=undefined-variable
                       ipykernel.zmqshell.ZMQInteractiveShell)
   except ImportError:
     return False
@@ -233,7 +234,7 @@ def _in_jupyter_shell() -> bool:
     return False
 
 
-def _project_number_from_client_id(client_id: Optional[str]) -> Optional[str]:
+def _project_number_from_client_id(client_id: str | None) -> str | None:
   """Returns the project number associated with the given OAuth client ID."""
   # Client IDs are of the form:
   # PROJECTNUMBER-BASE32STUFF.apps.googleusercontent.com.
@@ -242,10 +243,10 @@ def _project_number_from_client_id(client_id: Optional[str]) -> Optional[str]:
 
 
 def _obtain_and_write_token(
-    auth_code: Optional[str] = None,
-    code_verifier: Optional[str] = None,
-    scopes: Optional[Sequence[str]] = None,
-    redirect_uri: Optional[str] = None,
+    auth_code: str | None = None,
+    code_verifier: str | None = None,
+    scopes: Sequence[str] | None = None,
+    redirect_uri: str | None = None,
 ) -> None:
   """Obtains and writes credentials token based on an authorization code."""
   fetch_data = {}
@@ -282,7 +283,7 @@ def _obtain_and_write_token(
 
 
 def _display_auth_instructions_for_noninteractive(
-    auth_url: str, code_verifier: Union[bytes, str]
+    auth_url: str, code_verifier: bytes | str
 ) -> None:
   """Displays instructions for authenticating without blocking for user input."""
   # Python 3 `bytes` should be decoded to `str` if used as an argument of
@@ -292,38 +293,43 @@ def _display_auth_instructions_for_noninteractive(
   else:
     code_verifier_str = code_verifier
 
-  print('Paste the following address into a web browser:\n'
-        '\n'
-        '    {0}\n'
-        '\n'
-        'On the web page, please authorize access to your '
-        'Earth Engine account and copy the authentication code. '
-        'Next authenticate with the following command:\n'
-        '\n'
-        '    earthengine authenticate --code-verifier={1} '
-        '--authorization-code=PLACE_AUTH_CODE_HERE\n'.format(
-            auth_url, code_verifier_str))
+  print(
+      'Paste the following address into a web browser:\n'
+      '\n'
+      '    {}\n'
+      '\n'
+      'On the web page, please authorize access to your '
+      'Earth Engine account and copy the authentication code. '
+      'Next authenticate with the following command:\n'
+      '\n'
+      '    earthengine authenticate --code-verifier={} '
+      '--authorization-code=PLACE_AUTH_CODE_HERE\n'.format(
+          auth_url, code_verifier_str
+      )
+  )
 
 
 def _display_auth_instructions_with_print(
-    auth_url: str, coda: Optional[str] = None
+    auth_url: str, coda: str | None = None
 ) -> None:
   """Displays instructions for authenticating using a print statement."""
-  print('To authorize access needed by Earth Engine, open the following '
-        'URL in a web browser and follow the instructions. If the web '
-        'browser does not start automatically, please manually browse the '
-        'URL below.\n'
-        '\n'
-        '    {0}\n'
-        '\n{1}'.format(auth_url, coda or PASTE_CODA))
+  print(
+      'To authorize access needed by Earth Engine, open the following '
+      'URL in a web browser and follow the instructions. If the web '
+      'browser does not start automatically, please manually browse the '
+      'URL below.\n'
+      '\n'
+      '    {}\n'
+      '\n{}'.format(auth_url, coda or PASTE_CODA)
+  )
 
 
 def _display_auth_instructions_with_html(
-    auth_url: str, coda: Optional[str] = None
+    auth_url: str, coda: str | None = None
 ) -> None:
   """Displays instructions for authenticating using HTML code."""
   try:
-    IPython.display.display(IPython.display.HTML(
+    IPython.display.display(IPython.display.HTML(  # pylint: disable=undefined-variable
         """<p>To authorize access needed by Earth Engine, open the following
         URL in a web browser and follow the instructions:</p>
         <p><a href={0}>{0}</a></p>
@@ -339,14 +345,14 @@ def _base64param(byte_string: bytes) -> bytes:
   return base64.urlsafe_b64encode(byte_string).rstrip(b'=')
 
 
-def _nonce_table(*nonce_keys: str) -> Dict[str, str]:
+def _nonce_table(*nonce_keys: str) -> dict[str, str]:
   """Makes random nonces, and adds PKCE challenges for each _verifier nonce."""
   table = {}
   for key in nonce_keys:
     table[key] = _base64param(os.urandom(32))
     if key.endswith('_verifier'):
       # Generate a challenge that the server will use to ensure that requests
-      # only work with our verifiers.  https://tools.ietf.org/html/rfc7636
+      # only work with our verifiers. https://tools.ietf.org/html/rfc7636
       pkce_challenge = _base64param(hashlib.sha256(table[key]).digest())
       table[key.replace('_verifier', '_challenge')] = pkce_challenge
   return {k: v.decode() for k, v in table.items()}
@@ -376,8 +382,8 @@ def _no_gcloud() -> bool:
 
 
 def _load_gcloud_credentials(
-    scopes: Optional[Sequence[str]] = None,
-    quiet: Optional[bool] = None,
+    scopes: Sequence[str] | None = None,
+    quiet: bool | None = None,
     run_gcloud_legacy: bool = False,
 ) -> None:
   """Initializes credentials by running gcloud flows."""
@@ -429,7 +435,7 @@ def _start_server(port: int):
   class Handler(http.server.BaseHTTPRequestHandler):
     """Handles the OAuth callback and reports a success page."""
 
-    code: Optional[str] = None
+    code: str | None = None
 
     def do_GET(self) -> None:  # pylint: disable=invalid-name
       Handler.code = urllib.parse.parse_qs(
@@ -439,7 +445,7 @@ def _start_server(port: int):
       self.end_headers()
       self.wfile.write(
           b'\n\nGoogle Earth Engine authorization successful!\n\n\n'
-          b'Credentials have been retrieved.  Please close this window.\n\n'
+          b'Credentials have been retrieved. Please close this window.\n\n'
           b'  \xf0\x9f\x8c\x8d  \xe2\x9a\x99\xef\xb8\x8f  \xf0\x9f\x8c\x8f'
           b'  \xe2\x9a\x99\xef\xb8\x8f  \xf0\x9f\x8c\x8e ')  # Earth emoji
 
@@ -454,7 +460,7 @@ def _start_server(port: int):
       self.server = http.server.HTTPServer(('localhost', port), Handler)
       self.url = 'http://localhost:%s' % self.server.server_address[1]
 
-    def fetch_code(self) -> Optional[str]:
+    def fetch_code(self) -> str | None:
       self.server.handle_request()  # Blocks until a single request arrives.
       self.server.server_close()
       return Handler.code
@@ -463,24 +469,24 @@ def _start_server(port: int):
 
 
 def authenticate(
-    cli_authorization_code: Optional[str] = None,
-    quiet: Optional[bool] = None,
-    cli_code_verifier: Optional[str] = None,
-    auth_mode: Optional[str] = None,
-    scopes: Optional[Sequence[str]] = None,
+    cli_authorization_code: str | None = None,
+    quiet: bool | None = None,
+    cli_code_verifier: str | None = None,
+    auth_mode: str | None = None,
+    scopes: Sequence[str] | None = None,
     force: bool = False,
-) -> Optional[bool]:
+) -> bool | None:
   """Prompts the user to authorize access to Earth Engine via OAuth2.
 
   Args:
-    cli_authorization_code: An optional authorization code.  Supports CLI mode,
+    cli_authorization_code: An optional authorization code. Supports CLI mode,
       where the code is passed as an argument to `earthengine authenticate`.
     quiet: If true, do not require interactive prompts and force --no-browser
       mode for gcloud-legacy. If false, never supply --no-browser. Default is
       None, which autodetects the --no-browser setting.
-    cli_code_verifier: PKCE verifier to prevent auth code stealing.  Must be
+    cli_code_verifier: PKCE verifier to prevent auth code stealing. Must be
       provided if cli_authorization_code is given.
-    auth_mode: The authorization mode.  One of:
+    auth_mode: The authorization mode. One of:
         "colab" - use the Colab authentication flow.
         "notebook" - send user to notebook authenticator page. Intended for
           web users who do not run code locally. Credentials expire in 7 days.
@@ -508,6 +514,13 @@ def authenticate(
      Exception: on invalid arguments.
   """
 
+  if auth_mode == 'colab' and scopes is not None and set(scopes) != set(SCOPES):
+    raise ee_exception.EEException(
+        'Scopes cannot be customized when auth_mode is "colab". Please see'
+        ' https://developers.google.com/earth-engine/guides/auth#quick_reference_guide_and_table'
+        ' for more information.'
+    )
+
   if cli_authorization_code:
     _obtain_and_write_token(cli_authorization_code, cli_code_verifier, scopes)
     return
@@ -551,11 +564,11 @@ class Flow:
   """Holds state for auth flows."""
   code_verifier: str
   scopes: Sequence[str]
-  server: Optional[Any]
+  server: Any | None
   auth_url: str
 
   def __init__(
-      self, auth_mode: str = 'notebook', scopes: Optional[Sequence[str]] = None
+      self, auth_mode: str = 'notebook', scopes: Sequence[str] | None = None
   ):
     """Initializes auth URL and PKCE verifier, for use in save_code().
 
@@ -588,7 +601,7 @@ class Flow:
       # pylint:disable-next=broad-exception-raised
       raise ee_exception.EEException('Unknown auth_mode "%s"' % auth_mode)
 
-  def save_code(self, code: Optional[str] = None) -> None:
+  def save_code(self, code: str | None = None) -> None:
     """Fetches auth code if not given, and saves the generated credentials."""
     redirect_uri = None
     if self.server and not code:
@@ -596,7 +609,7 @@ class Flow:
       code = self.server.fetch_code()  # Waits for oauth callback
     _obtain_and_write_token(code, self.code_verifier, self.scopes, redirect_uri)
 
-  def display_instructions(self, quiet: Optional[bool] = None) -> bool:
+  def display_instructions(self, quiet: bool | None = None) -> bool:
     """Prints to stdout, and returns True if a browser should be opened."""
 
     if quiet:

ee/pixeltype.py

@@ -1,7 +1,7 @@
 """A wrapper for PixelTypes."""
 from __future__ import annotations
 
-from typing import Any, Dict, Optional, Union
+from typing import Any
 
 from ee import _arg_types
 from ee import apifunction
@@ -52,12 +52,12 @@ class PixelType(computedobject.ComputedObject):
 
   def __init__(
       self,
-      precision: Union[_arg_types.String],
+      precision: _arg_types.String,
       # pylint: disable=invalid-name
-      minValue: Optional[_arg_types.Number] = None,
-      maxValue: Optional[_arg_types.Number] = None,
+      minValue: _arg_types.Number | None = None,
+      maxValue: _arg_types.Number | None = None,
       # pylint: enable=invalid-name
-      dimensions: Optional[_arg_types.Integer] = None,
+      dimensions: _arg_types.Integer | None = None,
   ):
     """Creates a PixelType wrapper.
 
@@ -72,7 +72,7 @@ class PixelType(computedobject.ComputedObject):
     """
     self.initialize()
 
-    args: Dict[str, Any] = {'precision': precision}
+    args: dict[str, Any] = {'precision': precision}
     if minValue is not None:
       args['minValue'] = minValue
     if maxValue is not None:

ee/projection.py

@@ -1,7 +1,8 @@
 """A wrapper for Projections."""
 from __future__ import annotations
 
-from typing import Any, Dict, Optional, Sequence, Union
+from collections.abc import Sequence
+from typing import Any, Union
 
 from ee import _arg_types
 from ee import apifunction
@@ -45,9 +46,9 @@ class Projection(computedobject.ComputedObject):
   def __init__(
       self,
       crs: _arg_types.String,
-      transform: Optional[_NumberSequenceType] = None,
+      transform: _NumberSequenceType | None = None,
       # pylint: disable-next=invalid-name
-      transformWkt: Optional[_arg_types.String] = None,
+      transformWkt: _arg_types.String | None = None,
   ):
     """Creates a Projection wrapper.
 
@@ -80,7 +81,7 @@ class Projection(computedobject.ComputedObject):
         super().__init__(crs.func, crs.args, crs.varName)
         return
 
-    args: Dict[str, Any] = {'crs': crs}
+    args: dict[str, Any] = {'crs': crs}
     if transform is not None:
       args['transform'] = transform
     if transformWkt is not None: