Index

pyvider.ephemerals

This package defines the core abstractions for implementing ephemeral resources, which are temporary, stateful components like API clients or database connections.

Classes

BaseEphemeralResource

Bases: ABC, Generic[ResultType, PrivateStateType, ConfigType]

Abstract base class for an ephemeral resource.

Ephemeral resources manage temporary, stateful objects like API clients or database connections that have a limited lifetime and may need to be periodically renewed.

Functions

close abstractmethod async

close(
    ctx: EphemeralResourceContext[None, PrivateStateType],
) -> None

Closes the ephemeral resource and cleans up any connections.

Parameters:

Name	Type	Description	Default
ctx	EphemeralResourceContext[None, PrivateStateType]	The context containing the final private state.	required

Source code in pyvider/ephemerals/base.py

@abstractmethod
async def close(self, ctx: EphemeralResourceContext[None, PrivateStateType]) -> None:
    """
    Closes the ephemeral resource and cleans up any connections.

    Args:
        ctx: The context containing the final private state.
    """
    ...

get_schema abstractmethod classmethod

get_schema() -> PvsSchema

Returns the schema for the resource's configuration and result.

Source code in pyvider/ephemerals/base.py

@classmethod
@abstractmethod
def get_schema(cls) -> PvsSchema:
    """Returns the schema for the resource's configuration and result."""
    ...

open abstractmethod async

open(
    ctx: EphemeralResourceContext[ConfigType, None],
) -> tuple[ResultType, PrivateStateType, datetime]

Opens the ephemeral resource.

Parameters:

Name	Type	Description	Default
ctx	EphemeralResourceContext[ConfigType, None]	The context containing the resource's configuration.	required

Returns:

Type	Description
ResultType	A tuple containing:
PrivateStateType	The result data to be returned to Terraform.
datetime	The private state needed to manage the resource.
tuple[ResultType, PrivateStateType, datetime]	A UTC datetime indicating when the resource must be renewed.

Source code in pyvider/ephemerals/base.py

@abstractmethod
async def open(
    self, ctx: EphemeralResourceContext[ConfigType, None]
) -> tuple[ResultType, PrivateStateType, datetime]:
    """
    Opens the ephemeral resource.

    Args:
        ctx: The context containing the resource's configuration.

    Returns:
        A tuple containing:
        - The result data to be returned to Terraform.
        - The private state needed to manage the resource.
        - A UTC datetime indicating when the resource must be renewed.
    """
    ...

renew abstractmethod async

renew(
    ctx: EphemeralResourceContext[None, PrivateStateType],
) -> tuple[PrivateStateType, datetime]

Renews the ephemeral resource's lease or session.

Parameters:

Name	Type	Description	Default
ctx	EphemeralResourceContext[None, PrivateStateType]	The context containing the current private state.	required

Returns:

Type	Description
PrivateStateType	A tuple containing:
datetime	The new private state after renewal.
tuple[PrivateStateType, datetime]	A new UTC datetime indicating the next renewal time.

Source code in pyvider/ephemerals/base.py

@abstractmethod
async def renew(
    self, ctx: EphemeralResourceContext[None, PrivateStateType]
) -> tuple[PrivateStateType, datetime]:
    """
    Renews the ephemeral resource's lease or session.

    Args:
        ctx: The context containing the current private state.

    Returns:
        A tuple containing:
        - The *new* private state after renewal.
        - A new UTC datetime indicating the next renewal time.
    """
    ...

validate async

validate(config: ConfigType) -> list[str]

Performs custom validation on the configuration.

Returns:

Type	Description
list[str]	A list of error messages. An empty list indicates success.

Source code in pyvider/ephemerals/base.py

async def validate(self, config: ConfigType) -> list[str]:
    """
    Performs custom validation on the configuration.

    Returns:
        A list of error messages. An empty list indicates success.
    """
    return []

EphemeralResourceContext

Bases: BaseContext, Generic[ConfigType, PrivateStateType]

Context for ephemeral resource operations. Inherits diagnostic reporting capabilities from BaseContext.

Functions

register_ephemeral_resource

register_ephemeral_resource(
    name: str,
) -> Callable[[type], type]

Decorator to register an ephemeral resource under the 'ephemeral_resources' component type.

Parameters:

Name	Type	Description	Default
name	str	The unique name of the ephemeral resource to register.	required

Returns:

Name	Type	Description
class	Callable[[type], type]	The decorated ephemeral resource class.

Source code in pyvider/ephemerals/decorators.py

def register_ephemeral_resource(name: str) -> Callable[[type], type]:
    """
    Decorator to register an ephemeral resource under the 'ephemeral_resources' component type.

    Args:
        name (str): The unique name of the ephemeral resource to register.

    Returns:
        class: The decorated ephemeral resource class.
    """

    def decorator(cls: type) -> type:
        from pyvider.hub import hub

        hub.register("ephemeral_resource", name, cls)
        logger.debug(f"Registered ephemeral resource '{name}'")
        return cls

    return decorator