API Reference

This page contains all of the methods for the Provider and Context classes, the two interfaces exposed by pylumi to interact with Pulumi.

Context Reference

class pylumi.Context(name: Optional[str] = None, cwd: Optional[str] = None)

A context is a Python representation of a statey plugin context, which manages resource plugins. Basically this acts as an orchestration server which exposes a gRPC server and proxies communications with the actual resource plugin processes (my understandning).

Parameters:

  • name - (optional) Assign a name to the context; this name is unique,

so if two contexts are created with the same name then they will point to the same Provider object in the go runtime. * cwd - (optional) Pass a current working directory to use for the context.

install_plugin(plugin_kind: str, plugin_name: str, version: Optional[str] = None, reinstall: bool = False, exact: bool = False) → None

Install the given plugin into the current pulumi workspace.

Parameters:

  • plugin_kind - The kind of the plugin e.g. “resource”

  • plugin_name - The name of the plugin e.g. “aws”

  • version - (optional) The version of the plugin to install. If None, the default, the latest version of the plugin will be installed.

  • reinstall - (optional) Reinstall the plugin even if it is already installed, default False.

  • exact - (optional) Require that the installed plugin’s version match version exactly, by default greater version numbers are also considered acceptable. Not relevant if reinstall=True.

Returns: None

Pulumi docs: Reference: `plugins.go https://github.com/pulumi/pulumi/blob/master/sdk/go/common/workspace/plugins.go`_

list_plugins() → Sequence[str]

List the currently loaded plugins in this context.

Returns:

A list of plugin names that are currently loaded in the context.

Pulumi docs:

ListPlugins lists all plugins that have been loaded, with version information. Reference: ListPlugins

provider(name: str, config: Optional[Dict[str, Any]] = None, version: Optional[str] = None) → pylumi.provider.Provider

Get a Provider object with the given name. This just creates the provider object, no interaction is done with the Pulumi engine until configure() if called (or the provider is used as a context manager).

Parameters:

  • name - The name of the provider, e.g. ‘aws’.

  • config - (optional) configuration parameters for the provider.

Returns:

A new Provider instance.

Pulumi Docs:

Provider loads a new copy of the provider for a given package. If a provider for this package could not be found, or an error occurs while creating it, a non-nil error is returned. Reference: Provider

setup() → None

Set up this Pulumi context. This creates an interface in the Go runtime that can create and communicate with resource provider proce

Returns:

None

teardown() → None

Tear down this provider, removing associated OS resources such as plugin processes.

Returns:

None

AsyncContext Reference

class pylumi.AsyncContext(name: Optional[str] = None, cwd: Optional[str] = None, executor: Optional[concurrent.futures._base.Executor] = None)

This is an async version of Context, providing almost exactly the same interface, with three differences:

  • The provider() method returns an AsyncProvider, whose methods are all async. It is also an async context provider, so it should be used with the async for syntax

  • All methods other than provider() are async

  • It is an async context manager rather than a sync one

See the Context class for more information

async install_plugin(plugin_kind: str, plugin_name: str, version: Optional[str] = None, reinstall: bool = False, exact: bool = False) → None

Install the given plugin into the current pulumi workspace.

Parameters:

  • plugin_kind - The kind of the plugin e.g. “resource”

  • plugin_name - The name of the plugin e.g. “aws”

  • version - (optional) The version of the plugin to install. If None, the default, the latest version of the plugin will be installed.

  • reinstall - (optional) Reinstall the plugin even if it is already installed, default False.

  • exact - (optional) Require that the installed plugin’s version match version exactly, by default greater version numbers are also considered acceptable. Not relevant if reinstall=True.

Returns: None

Pulumi docs: Reference: `plugins.go https://github.com/pulumi/pulumi/blob/master/sdk/go/common/workspace/plugins.go`_

async list_plugins() → Sequence[str]

List the currently loaded plugins in this context.

Returns:

A list of plugin names that are currently loaded in the context.

Pulumi docs:

ListPlugins lists all plugins that have been loaded, with version information. Reference: ListPlugins

provider(name: str, config: Optional[Dict[str, Any]] = None, version: Optional[str] = None) → pylumi.provider.Provider

Get a Provider object with the given name. This just creates the provider object, no interaction is done with the Pulumi engine until configure() if called (or the provider is used as a context manager).

Parameters:

  • name - The name of the provider, e.g. ‘aws’.

  • config - (optional) configuration parameters for the provider.

Returns:

A new Provider instance.

Pulumi Docs:

Provider loads a new copy of the provider for a given package. If a provider for this package could not be found, or an error occurs while creating it, a non-nil error is returned. Reference: Provider

async setup() → None

Set up this Pulumi context. This creates an interface in the Go runtime that can create and communicate with resource provider proce

Returns:

None

async teardown() → None

Tear down this provider, removing associated OS resources such as plugin processes.

Returns:

None

Provider Reference

class pylumi.Provider(ctx: Context, name: str, config: Optional[Dict[str, Any]] = None, version: Optional[str] = None)

A pulumi provider logically maps to a real-world service or API, and in Pulumi terms maps to a resource provider process running locally that Pulumi communicates with via a gRPC interface. Common examples would be AWS or GCP.

check(urn: str, olds: Dict[str, Any], news: Dict[str, Any], allow_unknowns: bool = False) → Tuple[Optional[Dict[str, Any]], Optional[Dict[str, Any]]]

Validate the given resource configuration.

Parameters

  • urn - pulumi resource URN.

  • olds - old bag of properties

  • news - new bag of properties

  • allow_unknowns - (optional) allow unknown values in the output, default False.

Returns: (properties, errors) tuple, where properties is the validated bag of properties to be used for subsequent operations and errors is a list of validation errors, or None.

Pulumi Docs:

Check validates that the given property bag is valid for a resource of the given type and returns the inputs that should be passed to successive calls to Diff, Create, or Update for this resource.

Reference: Check

check_config(urn: str, olds: Dict[str, Any], news: Dict[str, Any], allow_unknowns: bool = False) → Dict[str, Any]

Validate the given provider configuration.

Parameters:

  • urn - pulumi resource URN.

  • olds - old bag of properties

  • news - new bag of properties

  • allow_unknowns - (optional) allow unknown values in the output, default False.

Returns:

(properties, errors) tuple, where properties is a validated version of the configuration that should be passed to configure() and errors is a list of errors indicating validation errors or None.

Pulumi Docs:

CheckConfig validates the configuration for this resource provider.

Reference: CheckConfig

configure(inputs: Optional[Dict[str, Any]] = None) → None

Configure this provider with the given configuration.

Parameters:

  • inputs - (optional) configure this provider with the given configuration

instead of the one passed in the constructor.

Returns:

None

Pulumi Docs:

Configure configures the resource provider with “globals” that control its behavior.

Reference: Configure

create(urn: str, news: Dict[str, Any], timeout: int = 60, preview: bool = False) → Dict[str, Any]

Create a pulumi resource.

Parameters:

  • urn - pulumi resource URN.

  • id - pulumi resource ID.

  • news - new bag of properties

  • timeout - (optional) timeout for the operation, default 60

  • preview - (optional) predict the future state of the resource, default False.

Returns:

A dictionary with the following keys:

  • ID - The ID of the new created resource

  • Properties - A dictonary of properties of the new created resource.

  • Status - An integer status code for the operation

Pulumi Docs:

Create allocates a new instance of the provided resource and returns its unique resource.ID.

Reference: Create

delete(urn: str, id: str, news: Dict[str, Any], timeout: int = 60) → int

Delete a pulumi resource.

Parameters:

  • urn - pulumi resource URN.

  • id - pulumi resource ID.

  • news - new bag of properties.

  • timeout - timeout for the operation, default 60.

Returns:

An integer status code.

Pulumi Docs:

Delete tears down an existing resource.

Reference: Delete

diff(urn: str, id: str, olds: Dict[str, Any], news: Dict[str, Any], allow_unknowns: bool = False, ignore_changes: Sequence[str] = ()) → Dict[str, Any]

Diff the given resource configurations.

Parameters:

  • urn - pulumi resource URN.

  • id - pulumi resource ID.

  • olds - old bag of properties

  • news - new bag of properties

  • allow_unknowns - (optional) allow unknown values in the output, default False.

Returns:

A dictionary response containing information about the diff.

Pulumi Docs:

Diff checks what impacts a hypothetical update will have on the resource’s properties.

Reference: Diff

diff_config(urn: str, olds: Dict[str, Any], news: Dict[str, Any], allow_unknowns: bool = False, ignore_changes: Sequence[str] = ()) → Dict[str, Any]

Diff the given provider configurations.

Parameters:

  • urn - pulumi resource URN.

  • olds - old bag of properties

  • news - new bag of properties

  • allow_unknowns - (optional) allow unknown values in the output, default False.

Returns:

A dictionary response containing information about the diff.

Pulumi Docs:

DiffConfig checks what impacts a hypothetical change to this provider’s configuration will have on the provider.

Reference: DiffConfig

get_plugin_info() → Dict[str, Any]

Get plugin information for this provider.

Returns:

A Python dictionary with the plugin information for this provider.

Pulumi Docs:

GetPluginInfo returns this plugin’s information.

Reference: GetProviderInfo

get_schema(version: int = 0, decode: bool = True) → Dict[str, Any]

Get the schema information about this provider.

Parameters:

  • version - (optional) specify a schema version for the provider. Default is 0.

  • decode - (optional) decode the raw JSON schema string and return a Python dictionary,

defaluts to True.

Returns:

A Python dictionary with the decoded JSON schema information if decode=True. Otherwise, a bytes object that can be decoded via json.loads().

Pulumi Docs:

GetSchema returns the schema for the provider.

Reference: GetSchema

invoke(member: str, args: Dict[str, Any]) → Dict[str, Any]

Invoke a function in the provider.

Parameters:

  • member - function name

  • args - function arguments, as a dictionary

Returns:

A dictionary with the result of the function invocation.

Pulumi Docs:

Invoke dynamically executes a built-in function in the provider.

Reference: Invoke

read(urn: str, id: str, inputs: Dict[str, Any], state: Dict[str, Any]) → Dict[str, Any]

Read the state of a pulumi resource.

Parameters:

  • urn - pulumi resource URN.

  • id - plumi resource ID.

  • inputs - input properties

  • state - properties from the current state of the resource

Returns:

A dictionary with the following keys:

  • ID - The ID of the read resource.

  • Inputs - The dictionary of inputs for the read resource.

  • Outputs - The dictionary of outputs for the read resource.

  • Status - An integer status code from the operation.

Pulumi Docs:

Read the current live state associated with a resource. Enough state must be include in the inputs to uniquely identify the resource; this is typically just the resource ID, but may also include some properties. If the resource is missing (for instance, because it has been deleted), the resulting property map will be nil.

Reference: Read

signal_cancellation() → None

Signal cancellation to the provider.

Returns:

None

Pulumi Docs:

SignalCancellation asks all resource providers to gracefully shut down and abort any ongoing operations. Operation aborted in this way will return an error (e.g., Update and Create will either a creation error or an initialization error. SignalCancellation is advisory and non-blocking; it is up to the host to decide how long to wait after SignalCancellation is called before (e.g.) hard-closing any gRPC connection.

Reference: SignalCancellation

teardown() → None

Tear down resources associated with this provider.

Returns:

None

update(urn: str, id: str, olds: Dict[str, Any], news: Dict[str, Any], timeout: int = 60) → Dict[str, Any]

Update the state of a pulumi resource.

Parameters:

  • urn - pulumi resource URN.

  • id - pulumi resource ID.

  • olds - old bag of properties.

  • news - new bag of properties.

  • timeout - timeout for the operation, default 60.

Returns:

A dictionary with the following keys:

  • ID - The ID of the new created resource

  • Properties - A dictonary of properties of the new created resource.

  • Status - An integer status code for the operation

Pulumi Docs:

Update updates an existing resource with new values.

Reference: Update

AsyncProvider Reference

class pylumi.AsyncProvider(ctx: AsyncContext, name: str, config: Optional[Dict[str, Any]] = None, version: Optional[str] = None)

This is an async version of Provider, providing almost exactly the same interface, with two differences: - All methods are async - It is an async context manager rather than a normal context manager, and thus the async for syntax must be used

See the Provider class for more information

async check(urn: str, olds: Dict[str, Any], news: Dict[str, Any], allow_unknowns: bool = False) → Tuple[Optional[Dict[str, Any]], Optional[Dict[str, Any]]]

Validate the given resource configuration.

Parameters

  • urn - pulumi resource URN.

  • olds - old bag of properties

  • news - new bag of properties

  • allow_unknowns - (optional) allow unknown values in the output, default False.

Returns: (properties, errors) tuple, where properties is the validated bag of properties to be used for subsequent operations and errors is a list of validation errors, or None.

Pulumi Docs:

Check validates that the given property bag is valid for a resource of the given type and returns the inputs that should be passed to successive calls to Diff, Create, or Update for this resource.

Reference: Check

async check_config(urn: str, olds: Dict[str, Any], news: Dict[str, Any], allow_unknowns: bool = False) → Dict[str, Any]

Validate the given provider configuration.

Parameters:

  • urn - pulumi resource URN.

  • olds - old bag of properties

  • news - new bag of properties

  • allow_unknowns - (optional) allow unknown values in the output, default False.

Returns:

(properties, errors) tuple, where properties is a validated version of the configuration that should be passed to configure() and errors is a list of errors indicating validation errors or None.

Pulumi Docs:

CheckConfig validates the configuration for this resource provider.

Reference: CheckConfig

async configure(inputs: Optional[Dict[str, Any]] = None) → None

Configure this provider with the given configuration.

Parameters:

  • inputs - (optional) configure this provider with the given configuration

instead of the one passed in the constructor.

Returns:

None

Pulumi Docs:

Configure configures the resource provider with “globals” that control its behavior.

Reference: Configure

async create(urn: str, news: Dict[str, Any], timeout: int = 60, preview: bool = False) → Dict[str, Any]

Create a pulumi resource.

Parameters:

  • urn - pulumi resource URN.

  • id - pulumi resource ID.

  • news - new bag of properties

  • timeout - (optional) timeout for the operation, default 60

  • preview - (optional) predict the future state of the resource, default False.

Returns:

A dictionary with the following keys:

  • ID - The ID of the new created resource

  • Properties - A dictonary of properties of the new created resource.

  • Status - An integer status code for the operation

Pulumi Docs:

Create allocates a new instance of the provided resource and returns its unique resource.ID.

Reference: Create

async delete(urn: str, id: str, news: Dict[str, Any], timeout: int = 60) → int

Delete a pulumi resource.

Parameters:

  • urn - pulumi resource URN.

  • id - pulumi resource ID.

  • news - new bag of properties.

  • timeout - timeout for the operation, default 60.

Returns:

An integer status code.

Pulumi Docs:

Delete tears down an existing resource.

Reference: Delete

async diff(urn: str, id: str, olds: Dict[str, Any], news: Dict[str, Any], allow_unknowns: bool = False, ignore_changes: Sequence[str] = ()) → Dict[str, Any]

Diff the given resource configurations.

Parameters:

  • urn - pulumi resource URN.

  • id - pulumi resource ID.

  • olds - old bag of properties

  • news - new bag of properties

  • allow_unknowns - (optional) allow unknown values in the output, default False.

Returns:

A dictionary response containing information about the diff.

Pulumi Docs:

Diff checks what impacts a hypothetical update will have on the resource’s properties.

Reference: Diff

async diff_config(urn: str, olds: Dict[str, Any], news: Dict[str, Any], allow_unknowns: bool = False, ignore_changes: Sequence[str] = ()) → Dict[str, Any]

Diff the given provider configurations.

Parameters:

  • urn - pulumi resource URN.

  • olds - old bag of properties

  • news - new bag of properties

  • allow_unknowns - (optional) allow unknown values in the output, default False.

Returns:

A dictionary response containing information about the diff.

Pulumi Docs:

DiffConfig checks what impacts a hypothetical change to this provider’s configuration will have on the provider.

Reference: DiffConfig

async get_plugin_info() → Dict[str, Any]

Get plugin information for this provider.

Returns:

A Python dictionary with the plugin information for this provider.

Pulumi Docs:

GetPluginInfo returns this plugin’s information.

Reference: GetProviderInfo

async get_schema(version: int = 0, decode: bool = True) → Dict[str, Any]

Get the schema information about this provider.

Parameters:

  • version - (optional) specify a schema version for the provider. Default is 0.

  • decode - (optional) decode the raw JSON schema string and return a Python dictionary,

defaluts to True.

Returns:

A Python dictionary with the decoded JSON schema information if decode=True. Otherwise, a bytes object that can be decoded via json.loads().

Pulumi Docs:

GetSchema returns the schema for the provider.

Reference: GetSchema

async invoke(member: str, args: Dict[str, Any]) → Dict[str, Any]

Invoke a function in the provider.

Parameters:

  • member - function name

  • args - function arguments, as a dictionary

Returns:

A dictionary with the result of the function invocation.

Pulumi Docs:

Invoke dynamically executes a built-in function in the provider.

Reference: Invoke

async read(urn: str, id: str, inputs: Dict[str, Any], state: Dict[str, Any]) → Dict[str, Any]

Read the state of a pulumi resource.

Parameters:

  • urn - pulumi resource URN.

  • id - plumi resource ID.

  • inputs - input properties

  • state - properties from the current state of the resource

Returns:

A dictionary with the following keys:

  • ID - The ID of the read resource.

  • Inputs - The dictionary of inputs for the read resource.

  • Outputs - The dictionary of outputs for the read resource.

  • Status - An integer status code from the operation.

Pulumi Docs:

Read the current live state associated with a resource. Enough state must be include in the inputs to uniquely identify the resource; this is typically just the resource ID, but may also include some properties. If the resource is missing (for instance, because it has been deleted), the resulting property map will be nil.

Reference: Read

async signal_cancellation() → None

Signal cancellation to the provider.

Returns:

None

Pulumi Docs:

SignalCancellation asks all resource providers to gracefully shut down and abort any ongoing operations. Operation aborted in this way will return an error (e.g., Update and Create will either a creation error or an initialization error. SignalCancellation is advisory and non-blocking; it is up to the host to decide how long to wait after SignalCancellation is called before (e.g.) hard-closing any gRPC connection.

Reference: SignalCancellation

async teardown() → None

Tear down resources associated with this provider.

Returns:

None

async update(urn: str, id: str, olds: Dict[str, Any], news: Dict[str, Any], timeout: int = 60) → Dict[str, Any]

Update the state of a pulumi resource.

Parameters:

  • urn - pulumi resource URN.

  • id - pulumi resource ID.

  • olds - old bag of properties.

  • news - new bag of properties.

  • timeout - timeout for the operation, default 60.

Returns:

A dictionary with the following keys:

  • ID - The ID of the new created resource

  • Properties - A dictonary of properties of the new created resource.

  • Status - An integer status code for the operation

Pulumi Docs:

Update updates an existing resource with new values.

Reference: Update

URN Reference

class pylumi.URN(type: str, name: str = '_', stack: str = '_', project: str = '_')

A URN builder class

classmethod parse(urn: str) → pylumi.urn.URN

Construct a URN object from a string. Does not need to be called directly, a string can be passed as a positional argument to URN e.g. URN(’urn:pulumi…’)

render() → str

Render this URN object to a string

replace(**kwargs) → pylumi.urn.URN

Return a new URN with the given components replaced