fenn.remote

Client-side remote execution helpers for the Fenn premium service.

This package is imported when fenn run or fenn auth is invoked.

class fenn.remote.Credentials(profile, api_key, host=None)[source]

Bases: object

A single resolved profile entry.

Parameters:

  • profile (str)

  • api_key (str)

  • host (str | None)

__init__(profile, api_key, host=None)
Parameters:

  • profile (str)

  • api_key (str)

  • host (str | None)

Return type:

None

api_key: str
host: str | None = None
profile: str
exception fenn.remote.CredentialsError[source]

Bases: RemoteError

Raised when an API key cannot be resolved or the credentials file is malformed.

exception fenn.remote.InsufficientCreditsError[source]

Bases: RemoteError

Raised when the server returns 402 Payment Required.

exception fenn.remote.JobFailedError(message, job_id, status)[source]

Bases: RemoteError

Raised when a remote job ends in a non-success terminal state.

Carries the final status string (failed / cancelled) and the job id so callers can re-fetch artifacts if they want to.

Parameters:

  • message (str)

  • job_id (str)

  • status (str)

Return type:

None

__init__(message, job_id, status)[source]
Parameters:

  • message (str)

  • job_id (str)

  • status (str)

Return type:

None

class fenn.remote.RemoteClient(host, api_key, *, session=None)[source]

Bases: object

Synchronous HTTP client for the Fenn remote execution service.

Parameters:

  • host (str)

  • api_key (str)

  • session (Optional[requests.Session])

__init__(host, api_key, *, session=None)[source]
Parameters:

  • host (str)

  • api_key (str)

  • session (Session | None)

Return type:

None

cancel(job_id)[source]
Parameters:

job_id (str)

Return type:

Dict[str, Any]

close()[source]
Return type:

None

download_artifacts(job_id, dest)[source]

Stream the artifact tarball to dest and return the path.

Parameters:

  • job_id (str)

  • dest (Path)

Return type:

Path

get_job(job_id)[source]
Parameters:

job_id (str)

Return type:

Dict[str, Any]

me()[source]
Return type:

Dict[str, Any]

stream_events(job_id)[source]

Open an SSE stream for job_id and yield decoded events.

Each yielded item is {"event": str, "data": Any} where data is json.loads’d if possible, otherwise the raw string.

Parameters:

job_id (str)

Return type:

Iterator[Iterator[Dict[str, Any]]]

submit_job(tarball_path, *, script, max_runtime, project=None, venv=None)[source]
Parameters:

  • tarball_path (Path)

  • script (str)

  • max_runtime (int)

  • project (str | None)

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

Return type:

Dict[str, Any]

exception fenn.remote.RemoteError[source]

Bases: Exception

Base class for all remote-execution client errors.

exception fenn.remote.WorkspaceTooLargeError[source]

Bases: RemoteError

Raised when the project workspace exceeds the configured size cap.

fenn.remote.load_credentials(profile='default')[source]

Return the [profile] section, or None if missing.

Parameters:

profile (str)

Return type:

Credentials | None

fenn.remote.pack_workspace(root, script, *, extra_includes=None, extra_excludes=None, max_bytes=104857600)[source]

Tar+gzip root into a tempfile.

Parameters:

  • root (Path) – Project directory to pack. Must be an existing directory.

  • script (Path) – Path (absolute or relative to root) of the entrypoint script. Must live underneath root. Returned in WorkspacePack.script_relpath as a POSIX relative path so the server can locate it in the unpacked workdir.

  • extra_includes (Iterable[Path] | None) – Paths that should be force-included even if they would otherwise be excluded.

  • extra_excludes (Iterable[str] | None) – Additional shell-glob patterns to skip.

  • max_bytes (int) – Cap on the uncompressed total. Raises WorkspaceTooLargeError if exceeded.

Returns:

A WorkspacePack pointing at the gzipped tarball.

Return type:

WorkspacePack

fenn.remote.resolve_api_key(*, explicit=None, profile=None)[source]

Resolve an API key using the documented priority chain.

Raises:

CredentialsError – if no key can be resolved.

Parameters:

  • explicit (str | None)

  • profile (str | None)

Return type:

Credentials

fenn.remote.write_credentials(api_key, *, profile='default', host=None)[source]

Persist api_key under [profile].

host is retained for backward-compatible callers; the CLI uses the fixed remote endpoint from fenn.remote.client.

Existing profiles are preserved. The file is created with mode 0o600 on POSIX; on Windows the umask is left to the OS (the file lives under the user’s home, which is already user-private).

Parameters:

  • api_key (str)

  • profile (str)

  • host (str | None)

Return type:

Path