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

ee/_cloud_api_utils.py

@@ -6,12 +6,13 @@ parameters and result values.
 """
 
 import calendar
+from collections.abc import Callable, Sequence
 import copy
 import datetime
 import json
 import os
 import re
-from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, Type, Union
+from typing import Any
 import warnings
 
 import google_auth_httplib2
@@ -23,6 +24,7 @@ import requests
 
 from ee import ee_exception
 
+
 # The Cloud API version.
 VERSION = os.environ.get('EE_CLOUD_API_VERSION', 'v1')
 
@@ -34,17 +36,24 @@ ASSET_NAME_PATTERN = (r'^projects/((?:\w+(?:[\w\-]+\.[\w\-]+)*?\.\w+\:)?'
 ASSET_ROOT_PATTERN = (r'^projects/((?:\w+(?:[\w\-]+\.[\w\-]+)*?\.\w+\:)?'
                       r'[a-z][a-z0-9\-]{4,28}[a-z0-9])/assets/?$')
 
-# The default user project to use when making Cloud API calls.
-_cloud_api_user_project: Optional[str] = None
+# Conversion from task state to operation state.
+TASK_TO_OPERATION_STATE = {
+    'READY': 'PENDING',
+    'RUNNING': 'RUNNING',
+    'CANCEL_REQUESTED': 'CANCELLING',
+    'COMPLETED': 'SUCCEEDED',
+    'CANCELLED': 'CANCELLED',
+    'FAILED': 'FAILED',
+}
 
 
 class _Http:
   """A httplib2.Http-like object based on requests."""
   _session: requests.Session
-  _timeout: Optional[float]
+  _timeout: float | None
 
   def __init__(
-      self, session: requests.Session, timeout: Optional[float] = None
+      self, session: requests.Session, timeout: float | None = None
   ):
     self._timeout = timeout
     self._session = session
@@ -53,11 +62,11 @@ class _Http:
       self,
       uri: str,
       method: str = 'GET',
-      body: Optional[str] = None,
-      headers: Optional[Dict[str, str]] = None,
-      redirections: Optional[int] = None,
-      connection_type: Optional[Type[Any]] = None,
-  ) -> Tuple[httplib2.Response, Any]:
+      body: str | None = None,
+      headers: dict[str, str] | None = None,
+      redirections: int | None = None,
+      connection_type: type[Any] | None = None,
+  ) -> tuple[httplib2.Response, Any]:
     """Makes an HTTP request using httplib2 semantics."""
     del connection_type  # Ignored
     del redirections  # Ignored
@@ -84,7 +93,7 @@ class _Http:
 
 
 def _wrap_request(
-    headers_supplier: Callable[[], Dict[str, Any]],
+    headers_supplier: Callable[[], dict[str, Any]],
     response_inspector: Callable[[Any], None],
 ) -> Callable[..., http.HttpRequest]:
   """Builds a callable that wraps an API request.
@@ -109,10 +118,10 @@ def _wrap_request(
       postproc: Callable[..., Any],
       uri: str,
       method: str = 'GET',
-      body: Optional[Any] = None,
-      headers: Optional[Any] = None,
-      methodId: Optional[Any] = None,
-      resumable: Optional[Any] = None,
+      body: Any | None = None,
+      headers: Any | None = None,
+      methodId: Any | None = None,
+      resumable: Any | None = None,
   ) -> http.HttpRequest:
     """Builds an HttpRequest, adding headers and response inspection."""
     additional_headers = headers_supplier()
@@ -135,22 +144,17 @@ def _wrap_request(
   return builder
 
 
-def set_cloud_api_user_project(cloud_api_user_project: str) -> None:
-  global _cloud_api_user_project
-  _cloud_api_user_project = cloud_api_user_project
-
-
 def build_cloud_resource(
     api_base_url: str,
     session: requests.Session,
-    api_key: Optional[str] = None,
-    credentials: Optional[Any] = None,
-    timeout: Optional[float] = None,
+    api_key: str | None = None,
+    credentials: Any | None = None,
+    timeout: float | None = None,
     num_retries: int = 1,
-    headers_supplier: Optional[Callable[[], Dict[str, Any]]] = None,
-    response_inspector: Optional[Callable[[Any], None]] = None,
-    http_transport: Optional[Any] = None,
-    raw: Optional[bool] = False,
+    headers_supplier: Callable[[], dict[str, Any]] | None = None,
+    response_inspector: Callable[[Any], None] | None = None,
+    http_transport: Any | None = None,
+    raw: bool | None = False,
 ) -> Any:
   """Builds an Earth Engine Cloud API resource.
 
@@ -222,9 +226,9 @@ def build_cloud_resource(
 
 def build_cloud_resource_from_document(
     discovery_document: Any,
-    http_transport: Optional[httplib2.Http] = None,
-    headers_supplier: Optional[Callable[..., Any]] = None,
-    response_inspector: Optional[Callable[..., Any]] = None,
+    http_transport: httplib2.Http | None = None,
+    headers_supplier: Callable[..., Any] | None = None,
+    response_inspector: Callable[..., Any] | None = None,
     raw: bool = False,
 ) -> discovery.Resource:
   """Builds an Earth Engine Cloud API resource from a description of the API.
@@ -256,12 +260,12 @@ def build_cloud_resource_from_document(
 
 
 def _convert_dict(
-    to_convert: Dict[str, Any],
-    conversions: Dict[str, Any],
-    defaults: Optional[Dict[str, Any]] = None,
+    to_convert: dict[str, Any],
+    conversions: dict[str, Any],
+    defaults: dict[str, Any] | None = None,
     key_warnings: bool = False,
     retain_keys: bool = False,
-) -> Dict[str, Any]:
+) -> dict[str, Any]:
   """Applies a set of conversion rules to a dict.
 
   Args:
@@ -287,14 +291,14 @@ def _convert_dict(
       not contain these keys.
     key_warnings: Whether to print warnings for input keys that are not mapped
       to anything in the output.
-    retain_keys: Whether or not to retain the state of dict.  If false, any keys
+    retain_keys: Whether or not to retain the state of dict. If false, any keys
       that don't show up in the conversions dict will be dropped from result.
 
   Returns:
     The "to_convert" dict with keys renamed, values converted, and defaults
     added.
   """
-  result: Dict[str, Any] = {}
+  result: dict[str, Any] = {}
   for key, value in to_convert.items():
     if key in conversions:
       conversion = conversions[key]
@@ -319,7 +323,7 @@ def _convert_dict(
 
 
 def _convert_value(
-    value: str, conversions: Dict[str, Any], default: Any) -> Any:
+    value: str, conversions: dict[str, Any], default: Any) -> Any:
   """Converts a value using a set of value mappings.
 
   Args:
@@ -382,7 +386,7 @@ def _convert_bounding_box_to_geo_json(bbox: Sequence[float]) -> str:
               lng_min, lat_min, lng_max, lat_max))
 
 
-def convert_get_list_params_to_list_assets_params(params) -> Dict[str, Any]:
+def convert_get_list_params_to_list_assets_params(params) -> dict[str, Any]:
   """Converts a getList params dict to something usable with listAssets."""
   params = _convert_dict(
       params, {
@@ -401,7 +405,7 @@ def convert_get_list_params_to_list_assets_params(params) -> Dict[str, Any]:
   return convert_list_images_params_to_list_assets_params(params)
 
 
-def convert_list_assets_result_to_get_list_result(result) -> List[Any]:
+def convert_list_assets_result_to_get_list_result(result) -> list[Any]:
   """Converts a listAssets result to something getList can return."""
   if 'assets' not in result:
     return []
@@ -434,7 +438,7 @@ def _convert_list_images_filter_params_to_list_assets_params(params) -> str:
     # query in a set of double quotes. We trivially avoid doubly-escaping the
     # quotes by replacing double quotes with single quotes.
     region = region.replace('"', "'")
-    query_strings.append('intersects("{}")'.format(region))
+    query_strings.append(f'intersects("{region}")')
     del params['region']
   if 'properties' in params:
     if isinstance(params['properties'], list) and any(
@@ -452,8 +456,8 @@ def _convert_list_images_filter_params_to_list_assets_params(params) -> str:
 
 
 def convert_list_images_params_to_list_assets_params(
-    params: Dict[str, Any]
-) -> Dict[str, Any]:
+    params: dict[str, Any]
+) -> dict[str, Any]:
   """Converts a listImages params dict to something usable with listAssets."""
   params = params.copy()
   extra_filters = _convert_list_images_filter_params_to_list_assets_params(
@@ -470,14 +474,14 @@ def is_asset_root(asset_name: str) -> bool:
   return bool(re.match(ASSET_ROOT_PATTERN, asset_name))
 
 
-def convert_list_images_result_to_get_list_result(result) -> List[Any]:
+def convert_list_images_result_to_get_list_result(result) -> list[Any]:
   """Converts a listImages result to something getList can return."""
   if 'images' not in result:
     return []
   return [_convert_image_for_get_list_result(i) for i in result['images']]
 
 
-def _convert_asset_for_get_list_result(asset) -> Dict[str, Any]:
+def _convert_asset_for_get_list_result(asset) -> dict[str, Any]:
   """Converts an EarthEngineAsset to the format returned by getList."""
   result = _convert_dict(
       asset, {
@@ -488,7 +492,7 @@ def _convert_asset_for_get_list_result(asset) -> Dict[str, Any]:
   return result
 
 
-def _convert_image_for_get_list_result(asset) -> Dict[str, Any]:
+def _convert_image_for_get_list_result(asset) -> dict[str, Any]:
   """Converts an Image to the format returned by getList."""
   result = _convert_dict(
       asset, {
@@ -534,12 +538,12 @@ def convert_asset_id_to_asset_name(asset_id: str) -> str:
   if re.match(ASSET_NAME_PATTERN, asset_id) or is_asset_root(asset_id):
     return asset_id
   elif asset_id.split('/')[0] in ['users', 'projects']:
-    return 'projects/earthengine-legacy/assets/{}'.format(asset_id)
+    return f'projects/earthengine-legacy/assets/{asset_id}'
   else:
-    return 'projects/earthengine-public/assets/{}'.format(asset_id)
+    return f'projects/earthengine-public/assets/{asset_id}'
 
 
-def split_asset_name(asset_name: str) -> Tuple[str, str]:
+def split_asset_name(asset_name: str) -> tuple[str, str]:
   """Splits an asset name into the parent and ID parts.
 
   Args:
@@ -559,12 +563,12 @@ def convert_operation_name_to_task_id(operation_name: str) -> str:
   return found.group(1) if found else operation_name
 
 
-def convert_task_id_to_operation_name(task_id: str) -> str:
+def convert_task_id_to_operation_name(project: str, task_id: str) -> str:
   """Converts a task ID to an Operation name."""
-  return 'projects/{}/operations/{}'.format(_cloud_api_user_project, task_id)
+  return f'projects/{project}/operations/{task_id}'
 
 
-def convert_params_to_image_manifest(params: Dict[str, Any]) -> Dict[str, Any]:
+def convert_params_to_image_manifest(params: dict[str, Any]) -> dict[str, Any]:
   """Converts params to an ImageManifest for ingestion."""
   return _convert_dict(
       params, {
@@ -574,7 +578,7 @@ def convert_params_to_image_manifest(params: Dict[str, Any]) -> Dict[str, Any]:
       retain_keys=True)
 
 
-def convert_params_to_table_manifest(params: Dict[str, Any]) -> Dict[str, Any]:
+def convert_params_to_table_manifest(params: dict[str, Any]) -> dict[str, Any]:
   """Converts params to a TableManifest for ingestion."""
   return _convert_dict(
       params, {
@@ -584,7 +588,7 @@ def convert_params_to_table_manifest(params: Dict[str, Any]) -> Dict[str, Any]:
       retain_keys=True)
 
 
-def convert_tilesets_to_one_platform_tilesets(tilesets: List[Any]) -> List[Any]:
+def convert_tilesets_to_one_platform_tilesets(tilesets: list[Any]) -> list[Any]:
   """Converts a tileset to a one platform representation of a tileset."""
   converted_tilesets = []
   for tileset in tilesets:
@@ -596,7 +600,7 @@ def convert_tilesets_to_one_platform_tilesets(tilesets: List[Any]) -> List[Any]:
   return converted_tilesets
 
 
-def convert_sources_to_one_platform_sources(sources: List[Any]) -> List[Any]:
+def convert_sources_to_one_platform_sources(sources: list[Any]) -> list[Any]:
   """Converts the sources to one platform representation of sources."""
   converted_sources = []
   for source in sources:
@@ -615,7 +619,7 @@ def convert_sources_to_one_platform_sources(sources: List[Any]) -> List[Any]:
   return converted_sources
 
 
-def encode_number_as_cloud_value(number: float) -> Dict[str, Union[float, str]]:
+def encode_number_as_cloud_value(number: float) -> dict[str, float | str]:
   # Numeric values in constantValue-style nodes end up stored in doubles. If the
   # input is an integer that loses precision as a double, use the int64 slot
   # ("integerValue") in ValueNode.
@@ -625,7 +629,7 @@ def encode_number_as_cloud_value(number: float) -> Dict[str, Union[float, str]]:
     return {'constantValue': number}
 
 
-def convert_algorithms(algorithms) -> Dict[str, Any]:
+def convert_algorithms(algorithms) -> dict[str, Any]:
   """Converts a ListAlgorithmsResult to the internal format.
 
   The internal code expects a dict mapping each algorithm's name to a dict
@@ -653,7 +657,7 @@ def convert_algorithms(algorithms) -> Dict[str, Any]:
   return dict(_convert_algorithm(algorithm) for algorithm in algs)
 
 
-def _convert_algorithm(algorithm: Dict[str, Any]) -> Tuple[str, Dict[str, Any]]:
+def _convert_algorithm(algorithm: dict[str, Any]) -> tuple[str, dict[str, Any]]:
   """Converts an Algorithm to the internal format."""
   # Strip leading 'algorithms/' from the name.
   algorithm_name = algorithm['name'][11:]
@@ -677,11 +681,11 @@ def _convert_algorithm(algorithm: Dict[str, Any]) -> Tuple[str, Dict[str, Any]]:
 
 
 def _convert_algorithm_arguments(
-    args: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    args: list[dict[str, Any]]) -> list[dict[str, Any]]:
   return [_convert_algorithm_argument(arg) for arg in args]
 
 
-def _convert_algorithm_argument(arg: Dict[str, Any]) -> Dict[str, Any]:
+def _convert_algorithm_argument(arg: dict[str, Any]) -> dict[str, Any]:
   return _convert_dict(
       arg, {
           'argumentName': 'name',
@@ -696,7 +700,7 @@ def _convert_algorithm_argument(arg: Dict[str, Any]) -> Dict[str, Any]:
       })
 
 
-def convert_to_image_file_format(format_str: Optional[str]) -> str:
+def convert_to_image_file_format(format_str: str | None) -> str:
   """Converts a legacy file format string to an ImageFileFormat enum value.
 
   Args:
@@ -723,7 +727,7 @@ def convert_to_image_file_format(format_str: Optional[str]) -> str:
     return format_str
 
 
-def convert_to_table_file_format(format_str: Optional[str]) -> str:
+def convert_to_table_file_format(format_str: str | None) -> str:
   """Converts a legacy file format string to a TableFileFormat enum value.
 
   Args:
@@ -746,7 +750,7 @@ def convert_to_table_file_format(format_str: Optional[str]) -> str:
     return format_str
 
 
-def convert_to_band_list(bands: Union[List[str], None, str]) -> List[str]:
+def convert_to_band_list(bands: list[str] | None | str) -> list[str]:
   """Converts a band list, possibly as CSV, to a real list of bands.
 
   Args:
@@ -766,7 +770,7 @@ def convert_to_band_list(bands: Union[List[str], None, str]) -> List[str]:
     raise ee_exception.EEException('Invalid band list ' + bands)
 
 
-def convert_to_visualization_options(params: Dict[str, Any]) -> Dict[str, Any]:
+def convert_to_visualization_options(params: dict[str, Any]) -> dict[str, Any]:
   """Extracts a VisualizationOptions from a param dict.
 
   Args:
@@ -829,14 +833,14 @@ def convert_to_visualization_options(params: Dict[str, Any]) -> Dict[str, Any]:
   return result
 
 
-def _convert_csv_numbers_to_list(value: str) -> List[float]:
+def _convert_csv_numbers_to_list(value: str) -> list[float]:
   """Converts a string containing CSV numbers to a list."""
   if not value:
     return []
   return [float(x) for x in value.split(',')]
 
 
-def convert_operation_to_task(operation: Dict[str, Any]) -> Dict[str, Any]:
+def convert_operation_to_task(operation: dict[str, Any]) -> dict[str, Any]:
   """Converts an Operation to a legacy Task."""
   result = _convert_dict(
       operation['metadata'], {
@@ -860,19 +864,32 @@ def convert_operation_to_task(operation: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def _convert_operation_state_to_task_state(state: str) -> str:
-  """Converts a state string from an Operation to the Task equivalent."""
+  """Converts an Operation state to a Task state."""
   return _convert_value(
-      state, {
-          'PENDING': 'READY',
-          'RUNNING': 'RUNNING',
-          'CANCELLING': 'CANCEL_REQUESTED',
-          'SUCCEEDED': 'COMPLETED',
-          'CANCELLED': 'CANCELLED',
-          'FAILED': 'FAILED'
-      }, 'UNKNOWN')
+      state,
+      {value: key for key, value in TASK_TO_OPERATION_STATE.items()},
+      'UNKNOWN',
+  )
+
+
+def _convert_task_state_to_operation_state(state: str) -> str:
+  """Converts a Task state to an Operation state."""
+  return _convert_value(state, TASK_TO_OPERATION_STATE, 'UNKNOWN')
+
+
+def convert_to_operation_state(state: str) -> str:
+  """Converts a Task state or an Operation state to an Operation state."""
+  # First, try converting the state assuming it's a task state.
+  operation_state = _convert_task_state_to_operation_state(state)
+  if operation_state != 'UNKNOWN':
+    return operation_state
+
+  # If it wasn't a task state, check if the input is a valid operation state.
+  valid_operation_states = set(TASK_TO_OPERATION_STATE.values())
+  return state if state in valid_operation_states else 'UNKNOWN'
 
 
-def convert_iam_policy_to_acl(policy: Dict[str, Any])  -> Dict[str, Any]:
+def convert_iam_policy_to_acl(policy: dict[str, Any])  -> dict[str, Any]:
   """Converts an IAM Policy proto to the legacy ACL format."""
   bindings = {
       binding['role']: binding.get('members', [])
@@ -892,7 +909,7 @@ def convert_iam_policy_to_acl(policy: Dict[str, Any])  -> Dict[str, Any]:
   return result
 
 
-def convert_acl_to_iam_policy(acl: Dict[str, Any]) -> Dict[str, Any]:
+def convert_acl_to_iam_policy(acl: dict[str, Any]) -> dict[str, Any]:
   """Converts the legacy ACL format to an IAM Policy proto."""
   owners = acl.get('owners', [])
   readers = acl.get('readers', [])
@@ -910,8 +927,8 @@ def convert_acl_to_iam_policy(acl: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def convert_to_grid_dimensions(
-    dimensions: Union[float, Sequence[float]]
-) -> Dict[str, float]:
+    dimensions: float | Sequence[float]
+) -> dict[str, float]:
   """Converts an input value to GridDimensions.
 
   Args:

ee/_helpers.py

@@ -7,10 +7,11 @@ referenced from there (e.g., "ee.profilePrinting").
 # Using lowercase function naming to match the JavaScript names.
 # pylint: disable=g-bad-name
 
+from collections.abc import Iterator
 import contextlib
 import json
 import sys
-from typing import Any, Dict, Iterator, Optional, TextIO, Union
+from typing import Any, TextIO
 
 from google.auth import crypt
 from google.oauth2 import service_account
@@ -21,13 +22,14 @@ from ee import data
 from ee import ee_exception
 from ee import oauth
 
-
 # Number of times to retry fetching profile data.
 _PROFILE_RETRIES = 5
 
 
 def ServiceAccountCredentials(
-    email: str, key_file: Optional[str] = None, key_data: Optional[str] = None
+    email: str | None = None,
+    key_file: str | None = None,
+    key_data: str | None = None,
 ) -> service_account.Credentials:
   """Configure OAuth2 credentials for a Google Service Account.
 
@@ -41,6 +43,10 @@ def ServiceAccountCredentials(
   Returns:
     An OAuth2 credentials object.
   """
+  if not email and not key_file and not key_data:
+    raise ValueError(
+        'At least one of email, key_file, or key_data must be specified.'
+    )
 
   # Assume anything that doesn't end in '.pem' is a JSON key.
   if key_file and not key_file.endswith('.pem'):
@@ -59,7 +65,7 @@ def ServiceAccountCredentials(
 
   # Probably a PEM key - just read the file into 'key_data'.
   if key_file:
-    with open(key_file, 'r') as file_:
+    with open(key_file) as file_:
       key_data = file_.read()
 
   # Raw PEM key.
@@ -69,7 +75,7 @@ def ServiceAccountCredentials(
 
 
 def call(
-    func: Union[str, apifunction.ApiFunction], *args, **kwargs
+    func: str | apifunction.ApiFunction, *args, **kwargs
 ) -> computedobject.ComputedObject:
   """Invoke the given algorithm with the specified args.
 
@@ -91,7 +97,7 @@ def call(
 
 # pylint: disable-next=redefined-builtin
 def apply(
-    func: Union[str, apifunction.ApiFunction], named_args: Dict[str, Any]
+    func: str | apifunction.ApiFunction, named_args: dict[str, Any]
 ) -> computedobject.ComputedObject:
   """Call a function with a dictionary of named arguments.
 
@@ -118,14 +124,13 @@ def profilePrinting(destination: TextIO = sys.stderr) -> Iterator[None]:
   The profile will be printed when the context ends, whether or not any error
   occurred within the context.
 
-  # Simple example:
-  with ee.profilePrinting():
-     print ee.Number(1).add(1).getInfo()
+  Example:
+    with ee.profilePrinting():
+      print(ee.Number(1).add(1).getInfo())
 
   Args:
     destination: A file-like object to which the profile text is written.
         Defaults to sys.stderr.
-
   """
   # Profile.getProfiles is `hidden`, so call it explicitly.
   get_profiles = apifunction.ApiFunction.lookup('Profile.getProfiles').call
@@ -135,12 +140,11 @@ def profilePrinting(destination: TextIO = sys.stderr) -> Iterator[None]:
       yield
   finally:
     # Make several attempts in case of transient errors.
-    attempts = _PROFILE_RETRIES
-    for i in range(_PROFILE_RETRIES):
+    for attempt in range(_PROFILE_RETRIES):
       try:
         profile_text = get_profiles(ids=profile_ids).getInfo()
         destination.write(profile_text)
         break
       except ee_exception.EEException as exception:
-        if i == attempts - 1:
+        if attempt == _PROFILE_RETRIES - 1:
           raise exception

ee/_state.py

@@ -0,0 +1,105 @@
+"""Stores the current state of the EE library."""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+from typing import Any
+
+# Rename to avoid redefined-outer-name warning.
+from google.oauth2 import credentials as credentials_lib
+import requests
+
+
+# The default project to use for Cloud API calls.
+DEFAULT_CLOUD_API_USER_PROJECT = 'earthengine-legacy'
+
+
+@dataclasses.dataclass()
+class _WorkloadTag:
+  """A helper class to manage the workload tag."""
+
+  _tag: str
+  _default: str
+
+  def __init__(self):
+    self._tag = ''
+    self._default = ''
+
+  def get(self) -> str:
+    return self._tag
+
+  def set(self, tag: int | str | None) -> None:
+    self._tag = self.validate(tag)
+
+  def set_default(self, new_default: int | str | None) -> None:
+    self._default = self.validate(new_default)
+
+  def reset(self) -> None:
+    self._tag = self._default
+
+  def validate(self, tag: int | str | None) -> str:
+    """Returns the validated tag or raises a ValueError.
+
+    Args:
+      tag: the tag to validate.
+
+    Raises:
+      ValueError if the tag does not match the expected format.
+    """
+    if not tag and tag != 0:
+      return ''
+    tag = str(tag)
+    if not re.fullmatch(r'([a-z0-9]|[a-z0-9][-_a-z0-9]{0,61}[a-z0-9])', tag):
+      validation_message = (
+          'Tags must be 1-63 characters, '
+          'beginning and ending with a lowercase alphanumeric character '
+          '([a-z0-9]) with dashes (-), underscores (_), '
+          'and lowercase alphanumerics between.'
+      )
+      raise ValueError(f'Invalid tag, "{tag}". {validation_message}')
+    return tag
+
+
+@dataclasses.dataclass()
+class EEState:
+  """Holds the configuration and initialized resources for an EE session."""
+
+  initialized: bool = False
+  credentials: credentials_lib.Credentials | None = None
+  api_base_url: str | None = None
+  tile_base_url: str | None = None
+  cloud_api_base_url: str | None = None
+  cloud_api_key: str | None = None
+  requests_session: requests.Session | None = None
+  cloud_api_resource: Any | None = None
+  cloud_api_resource_raw: Any | None = None
+  cloud_api_user_project: str | None = DEFAULT_CLOUD_API_USER_PROJECT
+  cloud_api_client_version: str | None = None
+  http_transport: Any | None = None
+  deadline_ms: int = 0
+  max_retries: int = 5
+  user_agent: str | None = None
+  workload_tag: _WorkloadTag = dataclasses.field(default_factory=_WorkloadTag)
+
+
+_state: EEState | None = None
+
+
+def get_state() -> EEState:
+  """Retrieves the EEState for the current execution context.
+
+  Returns:
+    The EEState for the current execution context.
+  """
+
+  global _state
+  if not _state:
+    _state = EEState()
+  return _state
+
+
+def reset_state() -> None:
+  """Resets the EEState to the default state."""
+  global _state
+  _state = None

ee/_utils.py

@@ -1,7 +1,8 @@
 """General decorators and helper methods which should not import ee."""
 
 import functools
-from typing import Any, Callable
+from typing import Any
+from collections.abc import Callable
 
 
 def accept_opt_prefix(*opt_args) -> Callable[..., Any]: