Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions .github/workflows/actions.lock
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
# Docs: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
'.github/workflows/ci.yml':
- 'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd'
'.github/workflows/publish-pypi.yml':
- 'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd'
- 'pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33'
'.github/workflows/release-doctor.yml':
- 'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd'
'.github/workflows/release-please.yml':
- 'actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547'
- 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020'
- 'pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1'
'.github/workflows/stlc-promote.yml':
- 'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd'
- 'actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547'
'.github/workflows/stlc-sync.yml':
- 'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd'
dependencies:
'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd':
ref: 'v6.0.2'
commit: 'sha1-de0fac2e4500dabe0009e67214ff5f5447ce83dd'
owner_id: 44036562
repo_id: 197814629
'actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547':
ref: 'v1.12.0'
commit: 'sha1-d72941d797fd3113feb6b93fd0dec494b13a2547'
owner_id: 44036562
repo_id: 642580244
'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020':
ref: 'v4.4.0'
commit: 'sha1-49933ea5288caeca8642d1e84afbd3f7d6820020'
owner_id: 44036562
repo_id: 189476904
'actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405':
ref: 'v6.2.0'
commit: 'sha1-a309ff8b426b58ec0e2a45f0f869d46889d02405'
owner_id: 44036562
repo_id: 192625525
'pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1':
ref: 'v4.3.0'
commit: 'sha1-b906affcce14559ad1aafd4ab0e942779e9f58b1'
owner_id: 21320719
repo_id: 262289747
'pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33':
ref: 'v1.14.2'
commit: 'sha1-dc37677b2e1c63e2034f94d8a5b11f265b73ba33'
owner_id: 647025
repo_id: 178055147
uses:
- 'actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405'
2 changes: 1 addition & 1 deletion .github/workflows/release-please.yml
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ jobs:
node-version: '18.20.2'

- name: Set up pnpm
uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4
uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4.3.0
with:
version: '9.11.0'
run_install: false
Expand Down
2 changes: 1 addition & 1 deletion .release-please-manifest.json
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
".": "0.28.0"
".": "0.29.0"
}
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,16 @@
# Changelog

## [0.29.0](https://github.com/kernel/hypeman-python/compare/v0.28.0...v0.29.0) (2026-11-16)


### Features

* Add force option to instance stop ([3ae497e](https://github.com/kernel/hypeman-python/commit/3ae497eeaf68f8a45cd2a4fd12073b80c26a0677))
* Add Windows hypervisor primitives ([5c037b9](https://github.com/kernel/hypeman-python/commit/5c037b9f9c5926025ba9e5852bea964b4e1ace7c))
* Integrate vendor VFIO vGPUs into the instance lifecycle ([24934bb](https://github.com/kernel/hypeman-python/commit/24934bb5e6f4a2ab636e0d893d056276ce2fd3dd))
* Place vGPU profiles the driver hides from creatable lists ([3578ec1](https://github.com/kernel/hypeman-python/commit/3578ec14db5cf79817e7e8606c9e260865deafd3))
* Update Hypeman build toolchains to Go 1.26.10 ([6a79c69](https://github.com/kernel/hypeman-python/commit/6a79c6927c90a1b35c971dcb749d1cddc0ecf8e3))

## [0.28.0](https://github.com/kernel/hypeman-python/compare/v0.27.0...v0.28.0) (2026-09-01)


Expand Down
2 changes: 1 addition & 1 deletion api.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ Methods:
- <code title="post /instances/{id}/start">client.instances.<a href="./src/hypeman/resources/instances/instances.py">start</a>(id, \*\*<a href="src/hypeman/types/instance_start_params.py">params</a>) -> <a href="./src/hypeman/types/instance.py">Instance</a></code>
- <code title="get /instances/{id}/stat">client.instances.<a href="./src/hypeman/resources/instances/instances.py">stat</a>(id, \*\*<a href="src/hypeman/types/instance_stat_params.py">params</a>) -> <a href="./src/hypeman/types/path_info.py">PathInfo</a></code>
- <code title="get /instances/{id}/stats">client.instances.<a href="./src/hypeman/resources/instances/instances.py">stats</a>(id) -> <a href="./src/hypeman/types/instance_stats.py">InstanceStats</a></code>
- <code title="post /instances/{id}/stop">client.instances.<a href="./src/hypeman/resources/instances/instances.py">stop</a>(id) -> <a href="./src/hypeman/types/instance.py">Instance</a></code>
- <code title="post /instances/{id}/stop">client.instances.<a href="./src/hypeman/resources/instances/instances.py">stop</a>(id, \*\*<a href="src/hypeman/types/instance_stop_params.py">params</a>) -> <a href="./src/hypeman/types/instance.py">Instance</a></code>
- <code title="get /instances/{id}/wait">client.instances.<a href="./src/hypeman/resources/instances/instances.py">wait</a>(id, \*\*<a href="src/hypeman/types/instance_wait_params.py">params</a>) -> <a href="./src/hypeman/types/wait_for_state_response.py">WaitForStateResponse</a></code>

## AutoStandby
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[project]
name = "hypeman"
version = "0.28.0"
version = "0.29.0"
description = "The official Python library for the hypeman API"
dynamic = ["readme"]
license = "Apache-2.0"
Expand Down
2 changes: 1 addition & 1 deletion src/hypeman/_version.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

__title__ = "hypeman"
__version__ = "0.28.0" # x-release-please-version
__version__ = "0.29.0" # x-release-please-version
59 changes: 41 additions & 18 deletions src/hypeman/resources/instances/instances.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
instance_list_params,
instance_logs_params,
instance_stat_params,
instance_stop_params,
instance_wait_params,
instance_start_params,
instance_create_params,
Expand Down Expand Up @@ -200,16 +201,19 @@ def create(

network: Network configuration for the instance

overlay_size: Writable overlay disk size (human-readable format like "10GB", "50G")
overlay_size: Writable overlay disk size (human-readable format like "10GB", "50G"). Omit this
field for macOS guests, which clone the image's complete boot disk instead.

platform: Target platform as os/arch[/variant] (e.g. "linux/amd64"), matching Docker
--platform. Omit for the host platform. Not a fixed enum: the os/arch[/variant]
grammar is validated server-side and invalid values return 400 invalid_platform.
Only os "linux" with arch amd64 or arm64 is accepted today.
platform: Target platform as os/arch[/variant]. Linux container guests support amd64 and
arm64. Experimental darwin/arm64 guests require an offline-imported macOS disk
image and vz on Apple silicon. Omit to use the cached native image or host
platform.

restart_policy: Whole-instance restart supervision policy.

size: Base memory size (human-readable format like "1GB", "512MB", "2G")
size: Base memory size (human-readable format like "1GB", "512MB", "2G"). macOS guests
default to their image's memory; explicit sizes must be at least 4 GiB in whole
MiB and within VZ host limits.

skip_guest_agent: Skip guest-agent installation during boot. When true, the exec and stat APIs
will not work for this instance. The instance will still run, but remote command
Expand All @@ -230,7 +234,8 @@ def create(
omit both expiration fields to disable automatic expiration. Mutually exclusive
with expires_at.

vcpus: Number of virtual CPUs
vcpus: Number of virtual CPUs. macOS guests default to their image's vCPUs; explicit
counts must be at least 2 and within VZ host limits.

volumes: Volumes to attach to the instance at creation time

Expand Down Expand Up @@ -536,7 +541,7 @@ def logs(
id: str,
*,
follow: bool | Omit = omit,
source: Literal["app", "vmm", "hypeman"] | Omit = omit,
source: Literal["app", "vmm", "hypeman", "swtpm"] | Omit = omit,
tail: int | Omit = omit,
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
# The extra values given here take precedence over values defined on the client or passed to this method.
Expand Down Expand Up @@ -819,6 +824,7 @@ def stop(
self,
id: str,
*,
force: bool | Omit = omit,
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
# The extra values given here take precedence over values defined on the client or passed to this method.
extra_headers: Headers | None = None,
Expand All @@ -827,9 +833,14 @@ def stop(
timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> Instance:
"""
Stop instance (graceful shutdown)
Stop instance (graceful shutdown, or forced power-off)

Args:
force: Power the VM off without asking the guest to shut down. Use when the guest state
will be discarded, for example before restoring a snapshot. A forced stop of a
macOS guest is never graceful, so it cannot be used for a stopped snapshot or
fork until the guest is booted and stopped gracefully again.

extra_headers: Send extra headers

extra_query: Add additional query parameters to the request
Expand All @@ -842,6 +853,7 @@ def stop(
raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
return self._post(
path_template("/instances/{id}/stop", id=id),
body=maybe_transform({"force": force}, instance_stop_params.InstanceStopParams),
options=make_request_options(
extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
),
Expand Down Expand Up @@ -1022,16 +1034,19 @@ async def create(

network: Network configuration for the instance

overlay_size: Writable overlay disk size (human-readable format like "10GB", "50G")
overlay_size: Writable overlay disk size (human-readable format like "10GB", "50G"). Omit this
field for macOS guests, which clone the image's complete boot disk instead.

platform: Target platform as os/arch[/variant] (e.g. "linux/amd64"), matching Docker
--platform. Omit for the host platform. Not a fixed enum: the os/arch[/variant]
grammar is validated server-side and invalid values return 400 invalid_platform.
Only os "linux" with arch amd64 or arm64 is accepted today.
platform: Target platform as os/arch[/variant]. Linux container guests support amd64 and
arm64. Experimental darwin/arm64 guests require an offline-imported macOS disk
image and vz on Apple silicon. Omit to use the cached native image or host
platform.

restart_policy: Whole-instance restart supervision policy.

size: Base memory size (human-readable format like "1GB", "512MB", "2G")
size: Base memory size (human-readable format like "1GB", "512MB", "2G"). macOS guests
default to their image's memory; explicit sizes must be at least 4 GiB in whole
MiB and within VZ host limits.

skip_guest_agent: Skip guest-agent installation during boot. When true, the exec and stat APIs
will not work for this instance. The instance will still run, but remote command
Expand All @@ -1052,7 +1067,8 @@ async def create(
omit both expiration fields to disable automatic expiration. Mutually exclusive
with expires_at.

vcpus: Number of virtual CPUs
vcpus: Number of virtual CPUs. macOS guests default to their image's vCPUs; explicit
counts must be at least 2 and within VZ host limits.

volumes: Volumes to attach to the instance at creation time

Expand Down Expand Up @@ -1358,7 +1374,7 @@ async def logs(
id: str,
*,
follow: bool | Omit = omit,
source: Literal["app", "vmm", "hypeman"] | Omit = omit,
source: Literal["app", "vmm", "hypeman", "swtpm"] | Omit = omit,
tail: int | Omit = omit,
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
# The extra values given here take precedence over values defined on the client or passed to this method.
Expand Down Expand Up @@ -1641,6 +1657,7 @@ async def stop(
self,
id: str,
*,
force: bool | Omit = omit,
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
# The extra values given here take precedence over values defined on the client or passed to this method.
extra_headers: Headers | None = None,
Expand All @@ -1649,9 +1666,14 @@ async def stop(
timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> Instance:
"""
Stop instance (graceful shutdown)
Stop instance (graceful shutdown, or forced power-off)

Args:
force: Power the VM off without asking the guest to shut down. Use when the guest state
will be discarded, for example before restoring a snapshot. A forced stop of a
macOS guest is never graceful, so it cannot be used for a stopped snapshot or
fork until the guest is booted and stopped gracefully again.

extra_headers: Send extra headers

extra_query: Add additional query parameters to the request
Expand All @@ -1664,6 +1686,7 @@ async def stop(
raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
return await self._post(
path_template("/instances/{id}/stop", id=id),
body=await async_maybe_transform({"force": force}, instance_stop_params.InstanceStopParams),
options=make_request_options(
extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
),
Expand Down
1 change: 1 addition & 0 deletions src/hypeman/types/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@
from .instance_list_params import InstanceListParams as InstanceListParams
from .instance_logs_params import InstanceLogsParams as InstanceLogsParams
from .instance_stat_params import InstanceStatParams as InstanceStatParams
from .instance_stop_params import InstanceStopParams as InstanceStopParams
from .instance_wait_params import InstanceWaitParams as InstanceWaitParams
from .restart_policy_param import RestartPolicyParam as RestartPolicyParam
from .snapshot_fork_params import SnapshotForkParams as SnapshotForkParams
Expand Down
6 changes: 5 additions & 1 deletion src/hypeman/types/gpu_profile.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,11 @@ class GPUProfile(BaseModel):
"""Available vGPU profile"""

available: int
"""Number of instances that can be created with this profile"""
"""
Number of additional instances of this profile the host can take if only this
profile is added. Counts for different profiles are not additive: an instance of
one profile can reduce availability of others on the same GPU.
"""

framebuffer_mb: int
"""Frame buffer size in MB"""
Expand Down
25 changes: 24 additions & 1 deletion src/hypeman/types/gpu_resource_status.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,40 @@
class GPUResourceStatus(BaseModel):
"""GPU resource status. Null if no GPUs available."""

allocatable_slots: int
"""
Free slots eligible for placement, matching admission control (excludes
quarantined VFs; 0 while VF health state is unavailable)
"""

mode: Literal["vgpu", "passthrough"]
"""GPU mode (vgpu for SR-IOV/mdev, passthrough for whole GPU)"""

quarantined_slots: int
"""VFs quarantined after guest driver init failures (vGPU mode only).

May overlap used_slots until the affected instance releases its VF.
"""

total_slots: int
"""Total slots (VFs for vGPU, physical GPUs for passthrough)"""

used_slots: int
"""Slots currently in use"""
"""Slots currently in use.

Includes quarantined VFs that are still assigned, so this can overlap
quarantined_slots.
"""

devices: Optional[List[PassthroughDevice]] = None
"""Physical GPUs (only in passthrough mode)"""

placement_disabled_reason: Optional[str] = None
"""
Present when allocatable_slots is 0 because the VF health state could not be
read or written rather than because the host is full. vGPU placement is refused
until the state file is repaired or the next write succeeds.
"""

profiles: Optional[List[GPUProfile]] = None
"""Available vGPU profiles (only in vGPU mode)"""
5 changes: 4 additions & 1 deletion src/hypeman/types/instance.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,11 @@
class GPU(BaseModel):
"""GPU information attached to the instance"""

device_path: Optional[str] = None
"""sysfs path of the assigned vGPU device"""

mdev_uuid: Optional[str] = None
"""mdev device UUID"""
"""mdev device UUID (mdev hosts only)"""

profile: Optional[str] = None
"""vGPU profile name"""
Expand Down
27 changes: 19 additions & 8 deletions src/hypeman/types/instance_create_params.py
Original file line number Diff line number Diff line change
Expand Up @@ -108,22 +108,29 @@ class InstanceCreateParams(TypedDict, total=False):
"""Network configuration for the instance"""

overlay_size: str
"""Writable overlay disk size (human-readable format like "10GB", "50G")"""
"""Writable overlay disk size (human-readable format like "10GB", "50G").

Omit this field for macOS guests, which clone the image's complete boot disk
instead.
"""

platform: str
"""Target platform as os/arch[/variant] (e.g.
"""Target platform as os/arch[/variant].

"linux/amd64"), matching Docker --platform. Omit for the host platform. Not a
fixed enum: the os/arch[/variant] grammar is validated server-side and invalid
values return 400 invalid_platform. Only os "linux" with arch amd64 or arm64 is
accepted today.
Linux container guests support amd64 and arm64. Experimental darwin/arm64 guests
require an offline-imported macOS disk image and vz on Apple silicon. Omit to
use the cached native image or host platform.
"""

restart_policy: RestartPolicyParam
"""Whole-instance restart supervision policy."""

size: str
"""Base memory size (human-readable format like "1GB", "512MB", "2G")"""
"""Base memory size (human-readable format like "1GB", "512MB", "2G").

macOS guests default to their image's memory; explicit sizes must be at least 4
GiB in whole MiB and within VZ host limits.
"""

skip_guest_agent: bool
"""
Expand Down Expand Up @@ -158,7 +165,11 @@ class InstanceCreateParams(TypedDict, total=False):
"""

vcpus: int
"""Number of virtual CPUs"""
"""Number of virtual CPUs.

macOS guests default to their image's vCPUs; explicit counts must be at least 2
and within VZ host limits.
"""

volumes: Iterable[VolumeMountParam]
"""Volumes to attach to the instance at creation time"""
Expand Down
Loading
Loading