Index

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

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],  # type: ignore[type-var]
) -> 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