Allow creating instances without waiting

[jvstme]

Add wait_for_status parameter to InstancesService.create, similar to ClustersService.create. Setting wait_for_status=None allows to return from the method immediately.

Resolves #79

[huksley]

Good idea!

Can this be rewritten to support the same syntax as for clusters, i.e.

...instance.create(
            # Set to None to not wait for provisioning but return immediately
            wait_for_status=verda_client.constants.cluster_status.PROVISIONING
)

[jvstme]

@huksley, even with wait_for_status=None, ClustersService.create still issues two API calls: POST /clusters followed by GET /clusters/<id>. We could implement the same behavior for instances, but ideally we’d like to avoid the second request so we never end up in the following situation:

• POST /instances — success
• GET /instances/<id> — error (API error, network issue, etc.)
• Result: the instance is created and starts accumulating charges, but its ID is never returned by InstancesService.create, leaving the application unaware of its existence.

Here are a few possible ways to address this:

1. Introduce a separate InstancesService.create_nowait method that does not call GET /instances/<id> (as proposed in this PR).

2. Make the return type of InstancesService.create depend on the wait_for_status parameter:

   • If wait_for_status is set, return an Instance.
   • If wait_for_status is None, return the instance ID as str (since POST /instances only returns the ID).

   Or introduce a separate parameter to control the return type.

3. Update the REST API so POST /instances returns a full Instance object. Since this is not backward-compatible, this would require either a new API version (/v2) or an opt-in mechanism via a request parameter.

Please let me know if any of these options seem reasonable, or if you have alternative suggestions.

[huksley]

Would it be ok if instance.create() with with wait_for_status=None would return instance populated with ID and values passed as request payload? that way, no get instance method will be needed

[jvstme]

@huksley, InstancesService.create doesn't have enough details to populate all instance fields, including price_per_hour, status, created_at, cpu, gpu, memory, etc.

[jvstme]

@huksley, I’ve added the wait_for_status parameter as you initially suggested. For now, I think we can live with the extra GET /instances/<id> call. This still isn’t ideal, since instance loss remains possible, but it’s less likely than before. We’d appreciate it if this could be improved further in the future, possibly by returning the full instance object from POST /instances.

I also had to add support for callables in wait_for_status; otherwise, it wouldn’t be backward compatible with the existing behavior, which checks for status != ordered instead of waiting for a specific status.

[huksley]

Wouldn't this completely change logic because it will not wait for status but immediately return instance without wait_for_status set?

[jvstme]

By default, wait_for_status is set to lambda s: s != InstanceStatus.ORDERED, which means the method doesn't return here and nothing changes for existing users that are not setting wait_for_status.

For those users that will decide to set wait_for_status=None, the method will return here immediately, which is the expected behavior.

The implementation is consistent with ClustersService.create.

[Copilot]

Pull request overview

This PR updates instance creation to optionally skip polling/waiting for a status transition after the create request.

Changes:

• Added a wait_for_status kw-only parameter to InstancesService.create to control whether/how to wait for a desired status.
• Updated polling logic to support either a specific status or a predicate callable.
• Added unit tests covering different wait_for_status behaviors.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
verda/instances/_instances.py	Adds wait_for_status parameter and adjusts create polling/early-return logic.
tests/unit_tests/instances/test_instances.py	Adds parameterized tests validating new waiting behavior for create.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The PR title/description says it adds InstancesService.create_nowait, but the diff only changes create() by introducing wait_for_status. Either add the described create_nowait method (e.g., a small wrapper calling create(..., wait_for_status=None)), or update the PR metadata to reflect the actual API change.

[jvstme]

Updated the description

[Copilot]

wait_for_status is typed as str | Callable[[str], bool], but the code/tests appear to use InstanceStatus values (and instance.status is compared to InstanceStatus). This should be typed consistently (e.g., InstanceStatus | Callable[[InstanceStatus], bool] | None) to avoid misleading API contracts and type-checking issues.

[jvstme]

InstanceStatus is a namespace for str constants. The actual type passed to wait_for_status is str and not InstanceStatus

[Copilot]

wait_for_status is typed as str | Callable[[str], bool], but the code/tests appear to use InstanceStatus values (and instance.status is compared to InstanceStatus). This should be typed consistently (e.g., InstanceStatus | Callable[[InstanceStatus], bool] | None) to avoid misleading API contracts and type-checking issues.

Suggested change

	if callable(wait_for_status):
	if wait_for_status(instance.status):
	return instance
	elif instance.status == wait_for_status:
	return instance
	status_value = getattr(instance.status, 'value', instance.status)
	if callable(wait_for_status):
	if wait_for_status(status_value):
	return instance
	else:
	target_status = getattr(wait_for_status, 'value', wait_for_status)
	if status_value == target_status:
	return instance

[jvstme]

InstanceStatus is a namespace for str constants. The actual type passed to wait_for_status is str and not InstanceStatus

[jvstme]

@huksley, do you have any additional comments or is the PR good to go for merging?