Deploy Python API
The Deploy class and result models from praisonai-deploy
The Deploy class runs, inspects, and tears down a deployment from Python.
from praisonai_deploy import Deploy
deploy = Deploy.from_yaml("agents.yaml")
result = deploy.deploy()
status = deploy.status()Quick Start
- From a YAML file
python from praisonai_deploy import Deploy deploy = Deploy.from_yaml("agents.yaml") result = deploy.deploy() - From a config object
python from praisonai_deploy import Deploy, DeployConfig, DeployType config = DeployConfig(type=DeployType.API) deploy = Deploy(config, agents_file="agents.yaml") result = deploy.deploy()
Methods
| Method | Returns | Description |
|---|---|---|
Deploy.from_yaml(agents_file="agents.yaml") | Deploy | Build a Deploy from the deploy: section of a YAML file |
Deploy(config, agents_file="agents.yaml") | Deploy | Build a Deploy from a DeployConfig object |
deploy(background=False) | DeployResult | Execute the deployment |
plan() | dict | Return the planned configuration without deploying |
status() | DeployStatus | Return the current service state |
doctor() | DoctorReport | Run readiness checks for the configured type |
destroy(force=False) | DestroyResult | Tear down the deployment |
Result Models
Each operation returns a typed model.
DeployResult
| Field | Type | Description |
|---|---|---|
success | bool | Whether the deployment succeeded |
message | str | Human-readable result message |
url | Optional[str] | Deployed service URL |
error | Optional[str] | Error message if it failed |
metadata | Dict[str, Any] | Additional metadata |
DeployStatus
| Field | Type | Default | Description |
|---|---|---|---|
state | ServiceState | (required) | running / stopped / pending / failed / not_found / unknown |
url | Optional[str] | None | Service URL/endpoint |
message | str | "" | Status message |
service_name | Optional[str] | None | Service name |
provider | Optional[str] | None | api / docker / <any registered provider>. Plugin providers surface here too, as their normalised name. |
region | Optional[str] | None | Deployment region |
healthy | bool | False | Whether the service is healthy |
instances_running | int | 0 | Running instances |
instances_desired | int | 0 | Desired instances |
created_at | Optional[str] | None | Creation timestamp |
updated_at | Optional[str] | None | Last update timestamp |
metadata | Dict[str, Any] | {} | Provider-specific metadata |
DeployStatus.to_dict() returns a JSON-serialisable dictionary.
Programmatic APIs
The registry — not the CloudProvider enum — is the authority on what is deployable.
from praisonai_deploy import (
CloudProvider, # built-in constants (aws, azure, gcp, fly, railway, render)
coerce_cloud_provider, # validate a name against the registry
list_cloud_providers, # every deployable name (built-ins + plugins)
)
from praisonai_deploy.providers import CloudProviderRegistry| Function | Returns | Description | |
|---|---|---|---|
list_cloud_providers() | list[str] | Every deployable name now. Built-ins first (declaration order), plugins appended sorted. | |
coerce_cloud_provider(value) | `CloudProvider \ | str` | A CloudProvider member for built-ins, a normalised lowercase str for plugins. Raises ValueError with a registry-derived list on unknown names. |
CloudProviderRegistry.default() | CloudProviderRegistry | The shared registry. Use list_names(), register(name, cls), and resolve(name) for programmatic use. |
from praisonai_deploy import list_cloud_providers, coerce_cloud_provider
print(list_cloud_providers()) # ['aws', 'azure', 'gcp', 'fly', 'railway', 'render', ...]
print(coerce_cloud_provider("AWS")) # CloudProvider.AWS (built-in keeps enum identity)
print(coerce_cloud_provider(" gcp ")) # CloudProvider.GCP (stripped + lowercased)DestroyResult
| Field | Type | Description |
|---|---|---|
success | bool | Whether the destroy succeeded |
message | str | Result message |
resources_deleted | List[str] | Deleted resource identifiers |
error | Optional[str] | Error message if it failed |
metadata | Dict[str, Any] | Additional metadata |
Common Patterns
Read the status as JSON.
from praisonai_deploy import Deploy
deploy = Deploy.from_yaml("agents.yaml")
status = deploy.status()
print(status.to_dict())Plan before deploying.
from praisonai_deploy import Deploy
deploy = Deploy.from_yaml("agents.yaml")
print(deploy.plan()) # dict describing the planned deploymentTear down when finished.
from praisonai_deploy import Deploy
deploy = Deploy.from_yaml("agents.yaml")
result = deploy.destroy(force=True)
print(result.resources_deleted)Best Practices
Check success before reading url
DeployResult.url is only set when success is True. Branch on result.success first.
Use to_dict() for logs and APIs
DeployStatus.to_dict() returns plain JSON types, ready to serialise into logs or an HTTP response.
Import from praisonai_deploy
Use from praisonai_deploy import Deploy — the praisonai.deploy path is a compatibility shim only.