From 8b2dd7bb7bcbee5f1eb285966d42f0813f60af35 Mon Sep 17 00:00:00 2001 From: Andrei Onel Date: Mon, 1 Sep 2025 22:51:59 +0300 Subject: [PATCH] Added reference documentation for: libs/python/pylume/pylume/models.py --- libs/python/pylume/pylume/models.py | 123 ++++++++++++++++++++++++++-- 1 file changed, 116 insertions(+), 7 deletions(-) diff --git a/libs/python/pylume/pylume/models.py b/libs/python/pylume/pylume/models.py index 664065ad..cd2ddb2b 100644 --- a/libs/python/pylume/pylume/models.py +++ b/libs/python/pylume/pylume/models.py @@ -3,6 +3,12 @@ import re from pydantic import BaseModel, Field, computed_field, validator, ConfigDict, RootModel class DiskInfo(BaseModel): + """Information about disk storage allocation. + + Attributes: + total: Total disk space in bytes + allocated: Currently allocated disk space in bytes + """ total: int allocated: int @@ -10,6 +16,15 @@ class VMConfig(BaseModel): """Configuration for creating a new VM. Note: Memory and disk sizes should be specified with units (e.g., "4GB", "64GB") + + Attributes: + name: Name of the virtual machine + os: Operating system type, either "macOS" or "linux" + cpu: Number of CPU cores to allocate + memory: Amount of memory to allocate with units + disk_size: Size of the disk to create with units + display: Display resolution in format "widthxheight" + ipsw: IPSW path or 'latest' for macOS VMs, None for other OS types """ name: str os: Literal["macOS", "linux"] = "macOS" @@ -23,7 +38,12 @@ class VMConfig(BaseModel): populate_by_alias = True class SharedDirectory(BaseModel): - """Configuration for a shared directory.""" + """Configuration for a shared directory. + + Attributes: + host_path: Path to the directory on the host system + read_only: Whether the directory should be mounted as read-only + """ host_path: str = Field(..., alias="hostPath") # Allow host_path but serialize as hostPath read_only: bool = False @@ -50,6 +70,16 @@ class VMRunOpts(BaseModel): ) def model_dump(self, **kwargs): + """Export model data with proper field name conversion. + + Converts shared directory fields to match API expectations when using aliases. + + Args: + **kwargs: Keyword arguments passed to parent model_dump method + + Returns: + dict: Model data with properly formatted field names + """ data = super().model_dump(**kwargs) # Convert shared directory fields to match API expectations if self.shared_directories and "by_alias" in kwargs and kwargs["by_alias"]: @@ -65,6 +95,18 @@ class VMRunOpts(BaseModel): return data class VMStatus(BaseModel): + """Status information for a virtual machine. + + Attributes: + name: Name of the virtual machine + status: Current status of the VM + os: Operating system type + cpu_count: Number of CPU cores allocated + memory_size: Amount of memory allocated in bytes + disk_size: Disk storage information + vnc_url: URL for VNC connection if available + ip_address: IP address of the VM if available + """ name: str status: str os: Literal["macOS", "linux"] @@ -80,38 +122,79 @@ class VMStatus(BaseModel): @computed_field @property def state(self) -> str: + """Get the current state of the VM. + + Returns: + str: Current VM status + """ return self.status @computed_field @property def cpu(self) -> int: + """Get the number of CPU cores. + + Returns: + int: Number of CPU cores allocated to the VM + """ return self.cpu_count @computed_field @property def memory(self) -> str: + """Get memory allocation in human-readable format. + + Returns: + str: Memory size formatted as "{size}GB" + """ # Convert bytes to GB gb = self.memory_size / (1024 * 1024 * 1024) return f"{int(gb)}GB" class VMUpdateOpts(BaseModel): + """Options for updating VM configuration. + + Attributes: + cpu: Number of CPU cores to update to + memory: Amount of memory to update to with units + disk_size: Size of disk to update to with units + """ cpu: Optional[int] = None memory: Optional[str] = None disk_size: Optional[str] = None class ImageRef(BaseModel): - """Reference to a VM image.""" + """Reference to a VM image. + + Attributes: + image: Name of the image + tag: Tag version of the image + registry: Registry hostname where image is stored + organization: Organization or namespace in the registry + """ image: str tag: str = "latest" registry: Optional[str] = "ghcr.io" organization: Optional[str] = "trycua" def model_dump(self, **kwargs): - """Override model_dump to return just the image:tag format.""" + """Override model_dump to return just the image:tag format. + + Args: + **kwargs: Keyword arguments (ignored) + + Returns: + str: Image reference in "image:tag" format + """ return f"{self.image}:{self.tag}" class CloneSpec(BaseModel): - """Specification for cloning a VM.""" + """Specification for cloning a VM. + + Attributes: + name: Name of the source VM to clone + new_name: Name for the new cloned VM + """ name: str new_name: str = Field(alias="newName") @@ -119,18 +202,44 @@ class CloneSpec(BaseModel): populate_by_alias = True class ImageInfo(BaseModel): - """Model for individual image information.""" + """Model for individual image information. + + Attributes: + imageId: Unique identifier for the image + """ imageId: str class ImageList(RootModel): - """Response model for the images endpoint.""" + """Response model for the images endpoint. + + A list-like container for ImageInfo objects that provides + iteration and indexing capabilities. + """ root: List[ImageInfo] def __iter__(self): + """Iterate over the image list. + + Returns: + Iterator over ImageInfo objects + """ return iter(self.root) def __getitem__(self, item): + """Get an item from the image list by index. + + Args: + item: Index or slice to retrieve + + Returns: + ImageInfo or list of ImageInfo objects + """ return self.root[item] def __len__(self): - return len(self.root) \ No newline at end of file + """Get the number of images in the list. + + Returns: + int: Number of images in the list + """ + return len(self.root) \ No newline at end of file