Begin summary command + misc (types, client, vendored sse_client, etc.)

cbensimon · cbensimon · commit 739983be97ae · 2026-02-06T17:31:38.000Z
diff --git a/src/huggingface_hub/_hot_reloading_client.py b/src/huggingface_hub/_hot_reloading_client.py
@@ -0,0 +1,38 @@
+"""
+"""
+
+from typing import Optional
+
+import httpx
+
+from .utils._headers import build_hf_headers
+from .utils._sse_client import SSEClient
+from ._hot_reloading_types import ApiGetReloadEventSourceData
+from ._hot_reloading_types import ApiGetReloadRequest
+
+
+HOT_RELOADING_PORT = 7887
+
+
+class ReloadClient:
+    def __init__(
+        self,
+        *,
+        host: str,
+        subdomain: str,
+        replica_hash: str,
+        token: Optional[str],
+    ):
+        base_host = host.replace(subdomain, f"{subdomain}--{HOT_RELOADING_PORT}")
+        self.client = httpx.Client(
+            base_url=f"{base_host}/--replicas/+{replica_hash}",
+            headers=build_hf_headers(token=token),
+        )
+
+    def get_reload(self, reload_id: str):
+        req = ApiGetReloadRequest(reloadId=reload_id)
+        with self.client.stream('POST', '/get-reload', json=req.model_dump()) as res:
+            assert res.status_code == 200, res.status_code # TODO: Raise specific error ? Return ?
+            for event in SSEClient(res.iter_bytes()).events():
+                if event.event == 'message':
+                    yield ApiGetReloadEventSourceData.model_validate_json(event.data)
diff --git a/src/huggingface_hub/_hot_reloading_types.py b/src/huggingface_hub/_hot_reloading_types.py
@@ -0,0 +1,100 @@
+"""
+"""
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class ReloadRegion(BaseModel):
+    startLine: int
+    startCol: int
+    endLine: int
+    endCol: int
+
+
+class ReloadOperationObject(BaseModel):
+    kind: Literal['add', 'update', 'delete']
+    region: ReloadRegion
+    objectType: str
+    objectName: str
+
+
+class ReloadOperationRun(BaseModel):
+    kind: Literal['run']
+    region: ReloadRegion
+    codeLines: str
+    stdout: str | None = None
+    stderr: str | None = None
+
+
+class ReloadOperationException(BaseModel):
+    kind: Literal['exception']
+    region: ReloadRegion
+    traceback: str
+
+
+class ReloadOperationError(BaseModel):
+    kind: Literal['error']
+    traceback: str
+
+
+class ReloadOperationUI(BaseModel):
+    kind: Literal['ui']
+    updated: bool
+
+
+class ApiCreateReloadRequest(BaseModel):
+    filepath: str
+    contents: str
+    reloadId: str | None = None
+
+
+class ApiCreateReloadResponseSuccess(BaseModel):
+    status: Literal['created']
+    reloadId: str
+
+
+class ApiCreateReloadResponseError(BaseModel):
+    status: Literal['alreadyReloading', 'fileNotFound']
+
+
+class ApiCreateReloadResponse(BaseModel):
+    res: ApiCreateReloadResponseError | ApiCreateReloadResponseSuccess
+
+
+class ApiGetReloadRequest(BaseModel):
+    reloadId: str
+
+
+class ApiGetReloadEventSourceData(BaseModel):
+    data: ReloadOperationError \
+        | ReloadOperationException \
+        | ReloadOperationObject \
+        | ReloadOperationRun \
+        | ReloadOperationUI \
+
+
+class ApiGetStatusRequest(BaseModel):
+    revision: str
+
+
+class ApiGetStatusResponse(BaseModel):
+    reloading: bool
+    uncommited: list[str]
+
+
+class ApiFetchContentsRequest(BaseModel):
+    filepath: str
+
+
+class ApiFetchContentsResponseError(BaseModel):
+    status: Literal['fileNotFound']
+
+
+class ApiFetchContentsResponseSuccess(BaseModel):
+    status: Literal['ok']
+    contents: str
+
+
+class ApiFetchContentsResponse(BaseModel):
+    res: ApiFetchContentsResponseError | ApiFetchContentsResponseSuccess
diff --git a/src/huggingface_hub/_space_api.py b/src/huggingface_hub/_space_api.py
@@ -15,7 +15,7 @@
 from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
-from typing import Optional
+from typing import Literal, Optional, Union
 
 from huggingface_hub.utils import parse_datetime
 
@@ -99,6 +99,18 @@ class SpaceStorage(str, Enum):
     LARGE = "large"
 
 
+@dataclass
+class SpaceHotReloading:
+    status: Literal["created", "canceled"]
+    replica_statuses: list[tuple[str, str]] # See hot_reloading.types.ApiCreateReloadResponse.res.status
+    raw: dict
+
+    def __init__(self, data: dict) -> None:
+        self.status = data["status"]
+        self.replica_statuses = data["replicaStatuses"]
+        self.raw = data
+
+
 @dataclass
 class SpaceRuntime:
     """
@@ -128,6 +140,7 @@ class SpaceRuntime:
     requested_hardware: Optional[SpaceHardware]
     sleep_time: Optional[int]
     storage: Optional[SpaceStorage]
+    hot_reloading: Optional[SpaceHotReloading]
     raw: dict
 
     def __init__(self, data: dict) -> None:
@@ -136,6 +149,7 @@ def __init__(self, data: dict) -> None:
         self.requested_hardware = data.get("hardware", {}).get("requested")
         self.sleep_time = data.get("gcTimeout")
         self.storage = data.get("storage")
+        self.hot_reloading = SpaceHotReloading(raw_hr) if (raw_hr := data.get("hotReloading")) is not None else None
         self.raw = data
 
 
diff --git a/src/huggingface_hub/cli/spaces.py b/src/huggingface_hub/cli/spaces.py
@@ -36,7 +36,7 @@
 from huggingface_hub.cli import _cli_utils
 from huggingface_hub.errors import CLIError, RepositoryNotFoundError, RevisionNotFoundError
 from huggingface_hub.file_download import hf_hub_download
-from huggingface_hub.hf_api import ExpandSpaceProperty_T, SpaceSort_T
+from huggingface_hub.hf_api import ExpandSpaceProperty_T, HfApi, SpaceSort_T
 from huggingface_hub.utils import are_progress_bars_disabled, disable_progress_bars, enable_progress_bars
 
 from ._cli_utils import (
@@ -210,3 +210,50 @@ def spaces_hot_reload(
         # hot-reloading summary
         # TODO
         pass
+
+
+def _spaces_hot_reloading_summary(
+    api: HfApi,
+    space_id: str,
+    commit_sha: str,
+    token: Optional[str],
+) -> None:
+    from huggingface_hub._hot_reloading_client import ReloadClient
+
+    space_info = api.space_info(space_id)
+    if (runtime := space_info.runtime) is None:
+        raise CLIError(f"Unable to read SpaceRuntime from {space_id} infos")
+    if (hot_reloading := runtime.hot_reloading) is None:
+        raise CLIError(f"Space {space_id} current running version has not been hot-reloaded")
+    if hot_reloading.status != "created":
+        typer.echo("...")
+        return
+
+    if (space_host := space_info.host) is None:
+        raise CLIError(f"Unexpected None host on hotReloaded Space")
+    if (space_subdomain := space_info.subdomain) is None:
+        raise CLIError(f"Unexpected None subdomain on hotReloaded Space")
+
+    clients = [ReloadClient(
+        host=space_host,
+        subdomain=space_subdomain,
+        replica_hash=hash,
+        token=token,
+    ) for hash, _ in hot_reloading.replica_statuses]
+
+    ...
+    # Fetch first client (display replica hash if multiple)
+    # Compare others
+    # Display final info (Success, Hot-reloading contains errors, etc.)
+
+
+
+@spaces_hot_reloading_cli.command("summary")
+def spaces_hot_reloading_summary(
+    space_id: Annotated[str, typer.Argument(help="The space ID (e.g. `username/repo-name`).")],
+    commit_sha: Annotated[str, typer.Argument(help="...")],
+    token: TokenOpt = None,
+):
+    """ Description """
+    api = get_hf_api(token=token)
+    _spaces_hot_reloading_summary(api, space_id, commit_sha, token)
diff --git a/src/huggingface_hub/utils/_sse_client.py b/src/huggingface_hub/utils/_sse_client.py
@@ -0,0 +1,136 @@
+"""
+Server Side Events (SSE) client for Python.
+
+Provides a generator of SSE received through an existing HTTP response.
+"""
+
+import logging
+
+__author__ = 'Maxime Petazzoni <maxime.petazzoni@bulix.org>'
+__email__ = 'maxime.petazzoni@bulix.org'
+__all__ = ['SSEClient']
+
+_FIELD_SEPARATOR = ':'
+
+
+class SSEClient(object):
+    """Implementation of a SSE client.
+
+    See http://www.w3.org/TR/2009/WD-eventsource-20091029/ for the
+    specification.
+    """
+
+    def __init__(self, event_source, char_enc='utf-8'):
+        """Initialize the SSE client over an existing, ready to consume
+        event source.
+
+        The event source is expected to be a binary stream and have a close()
+        method. That would usually be something that implements
+        io.BinaryIOBase, like an httplib or urllib3 HTTPResponse object.
+        """
+        self._logger = logging.getLogger(self.__class__.__module__)
+        self._logger.debug('Initialized SSE client from event source %s',
+                           event_source)
+        self._event_source = event_source
+        self._char_enc = char_enc
+
+    def _read(self):
+        """Read the incoming event source stream and yield event chunks.
+
+        Unfortunately it is possible for some servers to decide to break an
+        event into multiple HTTP chunks in the response. It is thus necessary
+        to correctly stitch together consecutive response chunks and find the
+        SSE delimiter (empty new line) to yield full, correct event chunks."""
+        data = b''
+        for chunk in self._event_source:
+            for line in chunk.splitlines(True):
+                data += line
+                if data.endswith((b'\r\r', b'\n\n', b'\r\n\r\n')):
+                    yield data
+                    data = b''
+        if data:
+            yield data
+
+    def events(self):
+        for chunk in self._read():
+            event = Event()
+            # Split before decoding so splitlines() only uses \r and \n
+            for line in chunk.splitlines():
+                # Decode the line.
+                line = line.decode(self._char_enc)
+
+                # Lines starting with a separator are comments and are to be
+                # ignored.
+                if not line.strip() or line.startswith(_FIELD_SEPARATOR):
+                    continue
+
+                data = line.split(_FIELD_SEPARATOR, 1)
+                field = data[0]
+
+                # Ignore unknown fields.
+                if field not in event.__dict__:
+                    self._logger.debug('Saw invalid field %s while parsing '
+                                       'Server Side Event', field)
+                    continue
+
+                if len(data) > 1:
+                    # From the spec:
+                    # "If value starts with a single U+0020 SPACE character,
+                    # remove it from value."
+                    if data[1].startswith(' '):
+                        value = data[1][1:]
+                    else:
+                        value = data[1]
+                else:
+                    # If no value is present after the separator,
+                    # assume an empty value.
+                    value = ''
+
+                # The data field may come over multiple lines and their values
+                # are concatenated with each other.
+                if field == 'data':
+                    event.__dict__[field] += value + '\n'
+                else:
+                    event.__dict__[field] = value
+
+            # Events with no data are not dispatched.
+            if not event.data:
+                continue
+
+            # If the data field ends with a newline, remove it.
+            if event.data.endswith('\n'):
+                event.data = event.data[0:-1]
+
+            # Empty event names default to 'message'
+            event.event = event.event or 'message'
+
+            # Dispatch the event
+            self._logger.debug('Dispatching %s...', event)
+            yield event
+
+    def close(self):
+        """Manually close the event source stream."""
+        self._event_source.close()
+
+
+class Event(object):
+    """Representation of an event from the event stream."""
+
+    def __init__(self, id=None, event='message', data='', retry=None):
+        self.id = id
+        self.event = event
+        self.data = data
+        self.retry = retry
+
+    def __str__(self):
+        s = '{0} event'.format(self.event)
+        if self.id:
+            s += ' #{0}'.format(self.id)
+        if self.data:
+            s += ', {0} byte{1}'.format(len(self.data),
+                                        's' if len(self.data) else '')
+        else:
+            s += ', no data'
+        if self.retry:
+            s += ', retry in {0}ms'.format(self.retry)
+        return s
