codeapi-client 0.4.1__py3-none-any.whl

codeapi/client/_sync/_web.py

@@ -0,0 +1,341 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+
+import httpx
+
+if TYPE_CHECKING:
+    from . import Client
+from codeapi.types import (
+    CodeInfo,
+    CodeType,
+    CodeZip,
+    Job,
+    JobStage,
+    JobStatus,
+    JobType,
+    JsonData,
+)
+
+
+class StoredWebClient:
+    def __init__(self, client: Client):
+        self._client = client
+
+    def run(
+        self,
+        code_id: str,
+    ) -> Job:
+        """Runs a stored Web page.
+
+        Args:
+            code_id (str): The code ID.
+
+        Returns:
+            Job: The created job.
+
+        Raises:
+            HTTPException: If the request fails.
+        """
+        url = f"{self._client.base_url}/jobs/code/{code_id}/run/web"
+
+        try:
+            response = httpx.post(
+                url,
+                headers=self._client.api_key_header,
+            )
+            response.raise_for_status()
+            return Job(**response.json())
+        except httpx.HTTPStatusError as e:
+            raise self._client._get_http_exception(httpx_error=e)
+
+    def list_info(self) -> list[CodeInfo]:
+        """List all stored Web code.
+
+        Returns:
+            list[CodeInfo]: List of Web code info.
+        """
+        return self._client.code.list_info(code_type=CodeType.WEB)
+
+    def delete(self, code_id: str) -> str:
+        """Delete stored Web code.
+
+        Args:
+            code_id (str): The code ID to delete.
+
+        Returns:
+            str: Deletion confirmation message.
+
+        Raises:
+            ValueError: If the code_id is not Web code.
+        """
+        # Verify this is actually Web code
+        code_info = self._client.code.get_info(code_id)
+        if code_info.code_type != CodeType.WEB:
+            raise ValueError(
+                f"Code '{code_id}' is {code_info.code_type}, not Web code. "
+                "Cannot delete non-Web code from Web client."
+            )
+
+        return self._client.code.delete(code_id)
+
+
+class WebJobsClient:
+    def __init__(self, client):
+        self._client = client
+
+    def list(
+        self,
+        job_status: JobStatus | None = None,
+        job_stage: JobStage | None = None,
+    ) -> List[Job]:
+        """List Web jobs.
+
+        Args:
+            job_status (JobStatus | None): Filter by job status.
+            job_stage (JobStage | None): Filter by job stage.
+
+        Returns:
+            list[Job]: List of Web jobs.
+        """
+        return self._client.jobs.list(
+            job_type=JobType.RUN_WEB,
+            job_status=job_status,
+            job_stage=job_stage,
+        )
+
+    def get_latest(self) -> Job | None:
+        """Get the most recent Web job.
+
+        Returns:
+            Job | None: The most recent Web job, or None if no jobs exist.
+        """
+        jobs = self.list()
+        return jobs[0] if jobs else None
+
+    def list_queued(self) -> List[Job]:
+        """Get all queued Web jobs.
+
+        Returns:
+            List[Job]: List of queued Web jobs.
+        """
+        return self.list(job_status=JobStatus.QUEUED)
+
+    def list_scheduled(self) -> List[Job]:
+        """Get all scheduled Web jobs.
+
+        Returns:
+            List[Job]: List of scheduled Web jobs.
+        """
+        return self.list(job_status=JobStatus.SCHEDULED)
+
+    def list_started(self) -> List[Job]:
+        """Get all started Web jobs.
+
+        Returns:
+            list[Job]: List of started Web jobs.
+        """
+        return self.list(job_status=JobStatus.STARTED)
+
+    def list_deferred(self) -> List[Job]:
+        """Get all deferred Web jobs.
+
+        Returns:
+            List[Job]: List of deferred Web jobs.
+        """
+        return self.list(job_status=JobStatus.DEFERRED)
+
+    def list_canceled(self) -> List[Job]:
+        """Get all canceled Web jobs.
+
+        Returns:
+            List[Job]: List of canceled Web jobs.
+        """
+        return self.list(job_status=JobStatus.CANCELED)
+
+    def list_stopped(self) -> List[Job]:
+        """Get all stopped Web jobs.
+
+        Returns:
+            List[Job]: List of stopped Web jobs.
+        """
+        return self.list(job_status=JobStatus.STOPPED)
+
+    def list_failed(self) -> List[Job]:
+        """Get all failed Web jobs.
+
+        Returns:
+            list[Job]: List of failed Web jobs.
+        """
+        return self.list(job_status=JobStatus.FAILED)
+
+    def list_finished(self) -> List[Job]:
+        """Get all finished Web jobs.
+
+        Returns:
+            list[Job]: List of finished Web jobs.
+        """
+        return self.list(job_status=JobStatus.FINISHED)
+
+    def list_timed_out(self) -> List[Job]:
+        """Get all timed out Web jobs.
+
+        Returns:
+            List[Job]: List of timed out Web jobs.
+        """
+        return self.list(job_status=JobStatus.TIMEOUT)
+
+    def list_pre_running(self) -> List[Job]:
+        """Get all pre-running Web jobs.
+
+        Returns:
+            List[Job]: List of pre-running Web jobs.
+        """
+        return self.list(job_stage=JobStage.PRE_RUNNING)
+
+    def list_running(self) -> List[Job]:
+        """Get all running Web jobs.
+
+        Returns:
+            List[Job]: List of running Web jobs.
+        """
+        return self.list(job_stage=JobStage.RUNNING)
+
+    def list_post_running(self) -> List[Job]:
+        """Get all post-running Web jobs.
+
+        Returns:
+            List[Job]: List of post-running Web jobs.
+        """
+        return self.list(job_stage=JobStage.POST_RUNNING)
+
+
+class WebClient:
+    def __init__(self, client: Client):
+        self._client = client
+        self.stored = StoredWebClient(client)
+        self.jobs = WebJobsClient(client)
+
+    def run(
+        self,
+        code_zip: CodeZip,
+    ) -> Job:
+        """Runs a Web page from code zip.
+
+        Args:
+            code_zip (CodeZip): The code zip.
+
+        Returns:
+            Job: The created job.
+
+        Raises:
+            HTTPException: If the request fails.
+        """
+        url = f"{self._client.base_url}/jobs/code/run/web"
+
+        files = self._client._prepare_files(code_zip=code_zip)
+
+        try:
+            response = httpx.post(
+                url,
+                headers=self._client.api_key_header,
+                files=files,
+            )
+            response.raise_for_status()
+            return Job(**response.json())
+        except httpx.HTTPStatusError as e:
+            raise self._client._get_http_exception(httpx_error=e)
+
+    def get_url(self, job_id: str) -> str:
+        """Gets the URL for a Web page.
+
+        Args:
+            job_id (str): The job ID.
+
+        Returns:
+            str: The Web page URL.
+        """
+        return self._client.get_subdomain_proxy_url(job_id)
+
+    def upload(
+        self,
+        code_zip: CodeZip,
+        code_name: str,
+        metadata: JsonData | dict | None = None,
+    ) -> str:
+        """Upload Web code.
+
+        Args:
+            code_zip (CodeZip): The code zip.
+            code_name (str): The name of the code.
+            metadata (JsonData | dict | None): The JSON metadata of the code.
+
+        Returns:
+            str: The code ID.
+        """
+        return self._client.code.upload(
+            code_zip=code_zip,
+            code_name=code_name,
+            code_type=CodeType.WEB,
+            metadata=metadata,
+        )
+
+    def is_healthy(self, job_id: str) -> bool:
+        """Checks whether launched Web page is healthy.
+
+        Args:
+            job_id (str): The ID of the Web page launch job.
+
+        Returns:
+            bool: True if Web page is healthy else False.
+
+        Raises:
+            HTTPException: If the request fails.
+        """
+        return self._client.jobs.is_healthy(job_id=job_id)
+
+    def await_healthy(self, job_id: str, timeout: float | None = None) -> Job:
+        """Waits for a Web page to become healthy.
+
+        Args:
+            job_id (str): The ID of the Web page run job.
+            timeout (float | None): Maximum time to wait in seconds. If None, waits indefinitely.
+
+        Returns:
+            Job: The job object of the Web page run job.
+
+        Raises:
+            HTTPException: If the request fails.
+            APIException: If the job enters stage POST_RUNNING unexpectedly.
+            TimeoutError: If the timeout is exceeded.
+        """
+        return self._client.jobs.await_healthy(job_id=job_id, timeout=timeout)
+
+    def ingest(
+        self,
+        code_zip: CodeZip,
+        code_name: str,
+        metadata: JsonData | dict | None = None,
+        build_pexenv: bool = False,
+        pexenv_python: str | None = None,
+    ) -> Job:
+        """Ingest Web code.
+
+        Args:
+            code_zip (CodeZip): The code zip.
+            code_name (str): The name of the code.
+            metadata (JsonData | dict | None): The JSON metadata of the code.
+            build_pexenv (bool): Whether to build the pex venv.
+            pexenv_python: (str | None): Python interpreter for the pex venv.
+
+        Returns:
+            Job: The code ingestion job.
+        """
+        return self._client.code.ingest(
+            code_zip=code_zip,
+            code_name=code_name,
+            code_type=CodeType.WEB,
+            metadata=metadata,
+            build_pexenv=build_pexenv,
+            pexenv_python=pexenv_python,
+        )

codeapi/client/_utils.py

@@ -0,0 +1,61 @@
+import os
+from pathlib import Path
+
+import aiofiles
+
+
+def get_file_dir(filepath: Path | str) -> str:
+    return str(Path(filepath).parent)
+
+
+def get_filename(filepath: Path | str) -> str:
+    return Path(filepath).name
+
+
+def file_exists(path: Path | str) -> bool:
+    return os.path.isfile(path)
+
+
+def read_file(path: Path | str) -> str:
+    return Path(path).read_text()
+
+
+async def read_file_async(path: Path | str) -> str:
+    async with aiofiles.open(path, mode="r") as f:
+        return await f.read()
+
+
+def read_bytes(path: Path | str) -> bytes:
+    return Path(path).read_bytes()
+
+
+async def read_bytes_async(path: Path | str) -> bytes:
+    async with aiofiles.open(path, mode="rb") as f:
+        return await f.read()
+
+
+def read_lines(path: Path | str) -> list[str]:
+    return read_file(path=path).splitlines()
+
+
+async def read_lines_async(path: Path | str) -> list[str]:
+    content = await read_file_async(path)
+    return content.splitlines()
+
+
+def write_file(path: Path | str, data: str) -> None:
+    Path(path).write_text(data=data)
+
+
+async def write_file_async(path: Path | str, data: str) -> None:
+    async with aiofiles.open(path, "w") as f:
+        await f.write(data)
+
+
+def write_bytes(path: Path | str, data: bytes) -> None:
+    Path(path).write_bytes(data=data)
+
+
+async def write_bytes_async(path: Path | str, data: bytes) -> None:
+    async with aiofiles.open(path, "wb") as f:
+        await f.write(data)

codeapi/types/__init__.py

@@ -0,0 +1,77 @@
+from ._api import (
+    API_KEY_HEADER,
+    ServerStatus,
+    ServicesHealth,
+    TokenRequest,
+    TokenResponse,
+)
+from ._base import CustomBaseModel
+from ._code import CodeInfo
+from ._enums import (
+    CodeAPIError,
+    CodeType,
+    ExitType,
+    JobStage,
+    JobStatus,
+    JobType,
+    WorkerDeployment,
+)
+from ._env import EnvVars
+from ._exc import CodeAPIException
+from ._job import Job
+from ._json import JsonData
+from ._stream import StreamOutput
+from ._swarm import HiveHeartbeat, SwarmStats
+from ._time import T_HOURS, T_MINUTES, T_SECONDS
+from ._zips import (
+    DOTENV_FILE,
+    EMPTY_ZIP_BYTES,
+    PEXENV_CMD,
+    PEXENV_FILE,
+    REQUIREMENTS_TXT,
+    CodeZip,
+    DataZip,
+    JobResult,
+    ZipBytes,
+)
+
+__all__ = [
+    "API_KEY_HEADER",
+    "CodeAPIError",
+    "CodeAPIException",
+    "DOTENV_FILE",
+    "EMPTY_ZIP_BYTES",
+    "PEXENV_CMD",
+    "PEXENV_FILE",
+    "REQUIREMENTS_TXT",
+    "CodeInfo",
+    "CodeType",
+    "CodeZip",
+    "CustomBaseModel",
+    "DataZip",
+    "EnvVars",
+    "ExitType",
+    "HiveHeartbeat",
+    "SwarmStats",
+    "Job",
+    "JobResult",
+    "JobStage",
+    "JobStatus",
+    "JobType",
+    "JsonData",
+    "ServerStatus",
+    "ServicesHealth",
+    "StreamOutput",
+    "T_HOURS",
+    "T_MINUTES",
+    "T_SECONDS",
+    "TokenRequest",
+    "TokenResponse",
+    "WorkerDeployment",
+    "ZipBytes",
+]
+
+
+for __name in __all__:
+    if not __name.startswith("__") and hasattr(locals()[__name], "__module__"):
+        setattr(locals()[__name], "__module__", __name__)

codeapi/types/_api.py

@@ -0,0 +1,30 @@
+from pydantic import BaseModel
+
+API_KEY_HEADER = "CodeAPI-Key"
+
+
+class TokenRequest(BaseModel):
+    user: str
+    ulid: str | None = None
+    ttl: int = -1  # [s]
+
+
+class TokenResponse(BaseModel):
+    token: str
+
+
+class ServerStatus(BaseModel):
+    is_healthy: bool
+
+
+class ServicesHealth(BaseModel):
+    redis_healthy: bool
+    storage_healthy: bool
+
+    @property
+    def all_healthy(self) -> bool:
+        return all(
+            getattr(self, attr)
+            for attr in self.__dict__
+            if isinstance(getattr(self, attr), bool)
+        )

codeapi/types/_base.py

@@ -0,0 +1,21 @@
+from pydantic import BaseModel
+from strenum import StrEnum
+
+
+class CustomBaseModel(BaseModel):
+    def __str__(self):
+        fields = self.__class__.__pydantic_fields__
+        field_values = ", ".join(
+            f"{k}={repr(v)}" for k, v in self.model_dump().items() if fields[k].repr
+        )
+        return f"{self.__class__.__name__}({field_values})"
+
+
+class CaseInsensitiveStrEnum(StrEnum):
+    @classmethod
+    def _missing_(cls, value):
+        if isinstance(value, str):
+            value = value.upper()
+            if value in cls._value2member_map_:
+                return cls._value2member_map_[value]
+        return None

codeapi/types/_code.py

@@ -0,0 +1,31 @@
+from pydantic import BaseModel, ConfigDict, field_serializer, field_validator
+
+from ._enums import CodeType
+from ._json import JsonData
+
+
+class CodeInfo(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    code_id: str
+    code_name: str
+    code_type: CodeType
+    metadata: JsonData
+
+    @field_serializer("metadata")
+    def serialize_metadata(self, value: JsonData) -> dict:
+        return dict(value)
+
+    @field_validator("metadata", mode="before")
+    @classmethod
+    def deserialize_metadata(cls, value: JsonData | dict) -> JsonData:
+        if isinstance(value, JsonData):
+            return value
+        return JsonData(value)
+
+    def __str__(self):
+        fields = self.__class__.__pydantic_fields__
+        field_values = ", ".join(
+            f"{k}={repr(v)}" for k, v in self.model_dump().items() if fields[k].repr
+        )
+        return f"{self.__class__.__name__}({field_values})"

codeapi/types/_enums.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from enum import Enum, auto
+from typing import Type
+
+from strenum import StrEnum
+
+
+class CodeType(StrEnum):
+    CLI = auto()
+    APP = auto()
+    MCP = auto()
+    WEB = auto()
+    LIB = auto()
+    UNKNOWN = auto()
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}.{self.name}"
+
+
+class ExitType(StrEnum):
+    NORMAL = auto()
+    ERROR = auto()
+    TIMEOUT = auto()
+    TERMINATED = auto()
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}.{self.name}"
+
+
+class JobType(StrEnum):
+    RUN_CLI = auto()
+    RUN_APP = auto()
+    RUN_MCP = auto()
+    RUN_WEB = auto()
+    INGEST = auto()
+    PEXENV = auto()
+    REQUIREMENTS = auto()
+
+    @classmethod
+    def from_code_type(cls, code_type: CodeType) -> JobType | None:
+        """Maps CodeType to corresponding JobType for run operations.
+
+        Args:
+            code_type (CodeType): The code type to map.
+
+        Returns:
+            JobType | None: The corresponding job type, or None if no mapping exists.
+        """
+        mapping = {
+            CodeType.CLI: cls.RUN_CLI,
+            CodeType.APP: cls.RUN_APP,
+            CodeType.MCP: cls.RUN_MCP,
+            CodeType.WEB: cls.RUN_WEB,
+            # CodeType.LIB has no corresponding run job type
+        }
+        return mapping.get(code_type)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}.{self.name}"
+
+
+class JobStage(StrEnum):
+    UNKNOWN = auto()
+    PRE_RUNNING = auto()
+    RUNNING = auto()
+    POST_RUNNING = auto()
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}.{self.name}"
+
+
+class JobStatus(StrEnum):
+    QUEUED = auto()
+    SCHEDULED = auto()
+    STARTED = auto()
+    DEFERRED = auto()
+    CANCELED = auto()
+    STOPPED = auto()
+    FAILED = auto()
+    FINISHED = auto()
+    TIMEOUT = auto()
+    UNKNOWN = auto()
+
+    @classmethod
+    def from_rq(cls: Type[JobStatus], rq_status: Enum | None) -> JobStatus:
+        if not rq_status:
+            return cls.UNKNOWN
+        return cls(str(rq_status.value).upper())
+
+    @property
+    def stage(self) -> JobStage:
+        if self == JobStatus.UNKNOWN:
+            return JobStage.UNKNOWN
+        if self in [JobStatus.QUEUED, JobStatus.SCHEDULED, JobStatus.DEFERRED]:
+            return JobStage.PRE_RUNNING
+        if self == JobStatus.STARTED:
+            return JobStage.RUNNING
+        return JobStage.POST_RUNNING  # [CANCELED, STOPPED, FAILED, FINISHED, TIMEOUT]
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}.{self.name}"
+
+
+class HiveStatus(StrEnum):
+    ALIVE = auto()
+    IDLE = auto()
+    BUSY = auto()
+    DEAD = auto()
+
+    @classmethod
+    def _missing_(cls, value):
+        if isinstance(value, str):
+            value = value.upper()
+            if value in cls._value2member_map_:
+                return cls._value2member_map_[value]
+        return None
+
+
+class WorkerDeployment(StrEnum):
+    LOCAL = auto()
+    HIVES = auto()
+
+    @classmethod
+    def _missing_(cls, value):
+        if isinstance(value, str):
+            value = value.upper()
+            if value in cls._value2member_map_:
+                return cls._value2member_map_[value]
+        return None
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}.{self.name}"
+
+
+class CodeAPIError(StrEnum):
+    CODE_NOT_FOUND = auto()
+    JOB_FAILED = auto()
+    NO_JOB_META = auto()
+    JOB_NOT_FINISHED = auto()
+    JOB_NOT_FOUND = auto()
+    JOB_POST_RUNNING = auto()
+    JOB_STILL_QUEUED = auto()
+    JOB_TIMED_OUT = auto()
+    NO_ASSOCIATED_CODE_ID = auto()
+    NO_STORAGE_BACKEND = auto()
+    UNKNOWN = auto()
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}.{self.name}"