fenn.remote

Client library for the Fenn remote execution service.

Used by fenn auth and fenn run. Public surface:

• fenn.remote.credentials — ~/.fenn/credentials credential store

• fenn.remote.client — HTTP/SSE client for the /v1/* API

• fenn.remote.workspace — project packing for upload

• fenn.remote.artifacts — artifact tarball extraction

• fenn.remote.exceptions — typed error hierarchy

exception fenn.remote.AuthError

Bases: RemoteError

The API key was missing, invalid, or revoked (HTTP 401/403).

class fenn.remote.Credentials(api_key: 'str', host: 'Optional[str]' = None)

Bases: object

Parameters:

• api_key (str)

• host (str | None)

__init__(api_key, host=None)

Parameters:

• api_key (str)

• host (str | None)

Return type:

None

api_key: str

host: str | None = None

exception fenn.remote.CredentialsError

Bases: RemoteError

No usable API key could be resolved locally.

exception fenn.remote.InsufficientCreditsError

Bases: RemoteError

The account does not have enough credits for the request (HTTP 402).

exception fenn.remote.JobFailedError(message, *, job_id=None, status=None)

Bases: RemoteError

A remote job finished in a non-success terminal state.

Parameters:

• message (str)

• job_id (Optional[str])

• status (Optional[str])

Return type:

None

__init__(message, *, job_id=None, status=None)

Parameters:

• message (str)

• job_id (str | None)

• status (str | None)

Return type:

None

exception fenn.remote.NetworkError

Bases: RemoteError

The remote host could not be reached.

class fenn.remote.RemoteClient(host, api_key, session=None)

Bases: object

Thin requests wrapper with bearer auth and typed errors.

Parameters:

• host (str)

• api_key (str)

• session (Optional[requests.Session])

__init__(host, api_key, session=None)

Parameters:

• host (str)

• api_key (str)

• session (Session | None)

Return type:

None

cancel(job_id)

Parameters:

job_id (str)

Return type:

dict

close()

Return type:

None

download_artifacts(job_id, dest)

Stream the job’s artifact tarball to dest and return it.

Parameters:

• job_id (str)

• dest (Path)

Return type:

Path

get_job(job_id)

Parameters:

job_id (str)

Return type:

dict

me()

Return the authenticated account: credits, plan, rate card.

Return type:

dict

stream_events(job_id)

Context manager yielding an iterator of parsed SSE events.

Parameters:

job_id (str)

submit_job(workspace_tar, *, script, max_runtime, project=None, venv=None, machine_class=None)

Upload a workspace and enqueue a job.

Matches the server contract (POST /v1/jobs): a tarball file part plus a meta JSON form field. Returns the server response, e.g. {"job_id": ..., "credit_hold": N, "credits_remaining": N}.

Parameters:

• workspace_tar (Path)

• script (str)

• max_runtime (int)

• project (str | None)

• venv (dict[str, Any] | None)

• machine_class (str | None)

Return type:

dict

exception fenn.remote.RemoteError

Bases: Exception

Base class for every error raised by fenn.remote.

exception fenn.remote.WorkspaceTooLargeError

Bases: RemoteError

The packed workspace exceeds the upload size limit.

fenn.remote.delete_credentials()

Remove the stored credential. Returns True if one existed.

Return type:

bool

fenn.remote.load_credentials()

Return the stored Credentials, or None if unset.

Return type:

Credentials | None

fenn.remote.mask_key(api_key)

Return a redacted form safe for terminal output.

Parameters:

api_key (str)

Return type:

str

fenn.remote.resolve_api_key()

Resolve an API key from env > credentials file.

Raises:

CredentialsError – when no key can be found anywhere.

Return type:

Credentials

fenn.remote.write_credentials(api_key, *, host=None)

Persist api_key and return the credentials file path.

Parameters:

• api_key (str)

• host (str | None)

Return type:

Path