Add environments REST API

Author: davidbrochart

.github/workflows/test.yml

@@ -18,8 +18,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout
-      uses: actions/checkout@v3
-    - uses: actions/setup-python@v4
+      uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: '3.13'
         cache: 'pip'
@@ -38,7 +38,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: [ '3.9', '3.10', '3.11', '3.12', '3.13' ]
+        python-version: [ '3.10', '3.11', '3.12', '3.13' ]
 
     steps:
     - name: Checkout
@@ -49,6 +49,8 @@ jobs:
         python-version: ${{ matrix.python-version }}
         cache: 'pip'
 
+    - uses: mamba-org/setup-micromamba@v2
+
     - name: Install hatch
       run: |
         python3 -m pip install --upgrade pip

jupyverse_api/jupyverse_api/asgi_websocket_transport.py

@@ -32,9 +32,7 @@ def __init__(self, event: wsproto.events.Event) -> None:
 
 
 class ASGIWebSocketAsyncNetworkStream(AsyncNetworkStream):
-    def __init__(
-        self, app: ASGIApp, scope: Scope, task_group: anyio.abc.TaskGroup
-    ) -> None:
+    def __init__(self, app: ASGIApp, scope: Scope, task_group: anyio.abc.TaskGroup) -> None:
         self.app = app
         self.scope = scope
         self._task_group = task_group
@@ -71,9 +69,7 @@ async def __aenter__(
     async def __aexit__(self, exc_type, exc_val, exc_tb) -> typing.Union[bool, None]:
         return await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
 
-    async def read(
-        self, max_bytes: int, timeout: typing.Optional[float] = None
-    ) -> bytes:
+    async def read(self, max_bytes: int, timeout: typing.Optional[float] = None) -> bytes:
         message: Message = await self.receive(timeout=timeout)
         type = message["type"]
 
@@ -93,9 +89,7 @@ async def read(
 
         return self.connection.send(event)
 
-    async def write(
-        self, buffer: bytes, timeout: typing.Optional[float] = None
-    ) -> None:
+    async def write(self, buffer: bytes, timeout: typing.Optional[float] = None) -> None:
         self.connection.receive_data(buffer)
         for event in self.connection.events():
             if isinstance(event, wsproto.events.Request):
@@ -169,9 +163,7 @@ def __init__(self, *args, **kwargs) -> None:
 
     async def __aenter__(self) -> "ASGIWebSocketTransport":
         async with contextlib.AsyncExitStack() as stack:
-            self._task_group = await stack.enter_async_context(
-                anyio.create_task_group()
-            )
+            self._task_group = await stack.enter_async_context(anyio.create_task_group())
             self.exit_stack = stack.pop_all()
 
         return self
@@ -191,9 +183,7 @@ async def handle_async_request(self, request: Request) -> Response:
 
         if scheme in {"ws", "wss"} or headers.get("upgrade") == "websocket":
             subprotocols: list[str] = []
-            if (
-                subprotocols_header := headers.get("sec-websocket-protocol")
-            ) is not None:
+            if (subprotocols_header := headers.get("sec-websocket-protocol")) is not None:
                 subprotocols = subprotocols_header.split(",")
 
             scope = {

jupyverse_api/jupyverse_api/cli.py

@@ -84,6 +84,18 @@
     type=str,
     help="Disable plugin.",
 )
+@click.option(
+    "--timeout",
+    type=float,
+    default=None,
+    help="The timeout for starting Jupyverse.",
+)
+@click.option(
+    "--stop-timeout",
+    type=float,
+    default=1,
+    help="The timeout for stopping Jupyverse.",
+)
 def main(
     debug: bool = False,
     show_config: bool = False,
@@ -96,6 +108,8 @@ def main(
     disable: tuple[str, ...] = (),
     allow_origin: tuple[str, ...] = (),
     query_param: tuple[str, ...] = (),
+    timeout: float | None = None,
+    stop_timeout: float = 1,
 ) -> None:
     query_params_dict = {}
     for qp in query_param:
@@ -118,6 +132,8 @@ def main(
         show_config=show_config,
         help_all=help_all,
         backend=backend,
+        timeout=timeout,
+        stop_timeout=stop_timeout,
     )  # type: ignore
 
 

jupyverse_api/jupyverse_api/environments/__init__.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from fastapi import APIRouter, Depends
+
+from jupyverse_api import Router
+
+from ..app import App
+from ..auth import Auth, User
+from .models import CreateEnvironment, Environment, EnvironmentStatus
+
+
+class Environments(Router, ABC):
+    def __init__(self, app: App, auth: Auth):
+        super().__init__(app=app)
+
+        router = APIRouter()
+
+        @router.delete("/api/environments/{environment_id}", status_code=204)
+        async def delete_environment(
+            environment_id: str,
+            user: User = Depends(auth.current_user(permissions={"sessions": ["write"]})),
+        ):
+            return await self.delete_environment(environment_id, user)
+
+        @router.post(
+            "/api/environments",
+            status_code=201,
+            response_model=Environment,
+        )
+        async def create_environment(
+            environment: CreateEnvironment,
+            user: User = Depends(auth.current_user(permissions={"sessions": ["write"]})),
+        ) -> Environment:
+            return await self.create_environment(environment, user)
+
+        @router.get("/api/environments/wait/{environment_id}")
+        async def wait_for_environment(environment_id: str) -> None:
+            return await self.wait_for_environment(environment_id)
+
+        @router.get("/api/environments/status/{environment_id}")
+        async def get_status(id: str) -> EnvironmentStatus:
+            return await self.get_status(id)
+
+        self.include_router(router)
+
+    @abstractmethod
+    async def delete_environment(
+        self,
+        id: str,
+        user: User,
+    ) -> None: ...
+
+    @abstractmethod
+    async def create_environment(
+        self,
+        environment: CreateEnvironment,
+        user: User,
+    ) -> Environment: ...
+
+    @abstractmethod
+    async def wait_for_environment(self, id: str) -> None: ...
+
+    @abstractmethod
+    async def get_status(self, id: str) -> EnvironmentStatus: ...
+
+    @abstractmethod
+    async def run_in_environment(self, id: str, command: str) -> int: ...
+
+    @abstractmethod
+    def add_package_manager(self, name: str, package_manager: PackageManager): ...
+
+
+class PackageManager(ABC):
+    @abstractmethod
+    async def create_environment(self, environment_file_path: str) -> str: ...
+
+    @abstractmethod
+    async def delete_environment(self, id: str) -> None: ...
+
+    @abstractmethod
+    async def wait_for_environment(self, id: str) -> None: ...
+
+    @abstractmethod
+    async def get_status(self, id: str) -> EnvironmentStatus: ...
+
+    @abstractmethod
+    async def run_in_environment(self, id: str, command: str) -> int: ...

jupyverse_api/jupyverse_api/environments/models.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+EnvironmentStatus = (
+    Literal["package manager not found"]
+    | Literal["environment uninitialized"]
+    | Literal["environment creation start"]
+    | Literal["environment creation success"]
+    | Literal["environment creation error"]
+    | Literal["environment file not found"]
+    | Literal["environment file not readable"]
+)
+
+
+class CreateEnvironment(BaseModel):
+    package_manager_name: str
+    environment_file_path: str
+
+
+class Environment(BaseModel):
+    id: str
+    status: EnvironmentStatus

jupyverse_api/jupyverse_api/kernel/__init__.py

@@ -46,7 +46,11 @@ def __init__(self) -> None:
         )
 
     @abstractmethod
-    async def start(self, *, task_status: TaskStatus[None] = TASK_STATUS_IGNORED,) -> None: ...
+    async def start(
+        self,
+        *,
+        task_status: TaskStatus[None] = TASK_STATUS_IGNORED,
+    ) -> None: ...
 
     @abstractmethod
     async def stop(self) -> None: ...

jupyverse_api/jupyverse_api/kernels/__init__.py

@@ -251,4 +251,3 @@ class KernelsConfig(Config):
         default=None,
     )
     require_yjs: bool = False
-    kernelenv_path: str = ""

jupyverse_api/jupyverse_api/kernels/models.py

@@ -6,6 +6,7 @@
 class KernelInfo(BaseModel):
     name: str | None = None
     id: str | None = None
+    environment_id: str | None = None
 
 
 class CreateSession(BaseModel):

jupyverse_api/pyproject.toml

@@ -29,7 +29,7 @@ dependencies = [
   "importlib_metadata >=3.6; python_version<'3.10'",
   "pydantic >=2,<3",
   "fastapi >=0.95.0,<1",
-  "fps >=0.5.1,<0.6.0",
+  "fps >=0.5.2,<0.6.0",
   "anyio >=3.6.2,<5",
   "anyioutils >=0.7.4",
 ]

plugins/environment_micromamba/COPYING.md

@@ -0,0 +1,59 @@
+# Licensing terms
+
+This project is licensed under the terms of the Modified BSD License
+(also known as New or Revised or 3-Clause BSD), as follows:
+
+- Copyright (c) 2025-, Jupyter Development Team
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this
+list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+Neither the name of the Jupyter Development Team nor the names of its
+contributors may be used to endorse or promote products derived from this
+software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## About the Jupyter Development Team
+
+The Jupyter Development Team is the set of all contributors to the Jupyter project.
+This includes all of the Jupyter subprojects.
+
+The core team that coordinates development on GitHub can be found here:
+https://github.com/jupyter/.
+
+## Our Copyright Policy
+
+Jupyter uses a shared copyright model. Each contributor maintains copyright
+over their contributions to Jupyter. But, it is important to note that these
+contributions are typically only changes to the repositories. Thus, the Jupyter
+source code, in its entirety is not the copyright of any single person or
+institution. Instead, it is the collective copyright of the entire Jupyter
+Development Team. If individual contributors want to maintain a record of what
+changes/contributions they have specific copyright on, they should indicate
+their copyright in the commit message of the change, when they commit the
+change to one of the Jupyter repositories.
+
+With this in mind, the following banner should be used in any source code file
+to indicate the copyright and license terms:
+
+    # Copyright (c) Jupyter Development Team.
+    # Distributed under the terms of the Modified BSD License.