Initialization and Authentication

A session can be built from any standard Google/Earth Engine credential via factory constructors, each holding a live, refreshable credential:

from eeclient import EESession

# Service-account key (dict or path)
session = EESession.from_service_account("sa-key.json")

# EARTHENGINE_TOKEN env var, else ~/.config/earthengine/credentials
session = EESession.from_earthengine_token()

# An existing google.auth Credentials object
session = EESession.from_google_credentials(creds, project="my-project")

# Application Default Credentials (explicit opt-in)
session = EESession.from_application_default()

# Resolve from the environment (opt-in): EARTHENGINE_TOKEN / EE OAuth file
session = EESession.from_default()

Credentials are never resolved implicitly — a bare EESession() constructor call is not supported; always use a from_* factory to build a session. To resolve from the environment explicitly, call EESession.from_default(), which walks local sources only, in this order:

1. EARTHENGINE_TOKEN environment variable

2. Earth Engine credentials file (~/.config/earthengine/credentials)

The credentials file is accepted only when it holds an OAuth refresh token — the file earthengine authenticate writes. A service-account key at that path is refused with ServiceAccountFileRefusedError: it is a machine-wide identity, so resolving it implicitly would give every caller on the host the same Earth Engine account. To use it anyway, opt in explicitly:

session = EESession.from_default(allow_service_account_file=True)

Prefer EESession.from_service_account("sa-key.json"), which names the key you mean. Any other file shape — unparsable, or without a refresh token — raises CredentialsFileUnrecognizedError. Both errors subclass CredentialsResolutionError, so a single except covers every way from_default() can fail to resolve.

Application Default Credentials are not included — call EESession.from_application_default() to use them.

To see which source a session ended up using, inspect session.auth_mode (the credential kind: file/oauth/service_account/adc/sepal) and session.auth_source (the precise origin: earthengine_token/ee_oauth_file/ee_service_account_file/service_account/application_default/google_credentials/sepal_file/sepal_session).

Making API Calls

After initializing the session, use the operations property to access the key GEE methods. For example, you can retrieve information about Earth Engine objects, generate map IDs, or fetch asset details:

import ee

# Initialize the Earth Engine library (this can use any authentication method/account)
# The purpose of this is to ensure the ee library is available for use
ee.Initialize()

# Use the operations available in the session
result_info = session.operations.get_info(ee.Number(5))
print(result_info) # the GEE server call is done using the custom EE client

# Example: Generate a map ID for an Earth Engine image
image = ee.Image('COPERNICUS/S2/20190726T104031_20190726T104035_T31TGL')
map_id = session.operations.get_map_id(image)
print(map_id)

# Example: Retrieve asset information
asset_info = session.operations.get_asset("users/your_username/your_asset")
print(asset_info)

Forking and Branching

1. Fork the repository.

2. Create a new branch:

   git checkout -b feature-branch

3. Commit your changes:

   git commit -am 'Add new feature'

4. Push the branch:

   git push origin feature-branch

5. Create a new Pull Request.