API Modules

This page is rendered directly from the module’s Python source using Sphinx autodoc.

dxaws_acm.manager

ACM manager implementing the Base Manager Pattern.

class dxaws_acm.manager.AcmManager(*, provider: 'ProviderBase | None' = None, dns: 'DnsManager | None' = None, o11y: 'O11y' = <factory>)[source]

Bases: object

apply(plan: AcmPlan, *, options: ApplyOptions | None = None) → AcmOutputs[source]
dns: DnsManager | None
execute(desired: AcmDesired, *, options: ExecuteOptions | None = None) → AcmManagerResult[source]
get_current(desired: AcmDesired) → AcmCurrent[source]
o11y: O11y
plan(desired: AcmDesired, current: AcmCurrent | None = None) → AcmPlan[source]
provider: ProviderBase | None
class dxaws_acm.manager.ApplyOptions(*, max_wait_seconds: 'int' = 900, poll_interval_seconds: 'int' = 15, dns_ttl: 'int' = 60, emit_events: 'bool' = True)[source]

Bases: object

dns_ttl: int
emit_events: bool
max_wait_seconds: int
poll_interval_seconds: int
class dxaws_acm.manager.ExecuteOptions(*, apply_options: 'ApplyOptions | None' = None, emit_events: 'bool' = True)[source]

Bases: object

apply_options: ApplyOptions | None
emit_events: bool

dxaws_acm.planner

Planner for ACM manager lifecycle (v0.1.0).

dxaws_acm.planner.plan_acm(*, desired: AcmDesired, current: AcmCurrent) → AcmPlan[source]

dxaws_acm.models

class dxaws_acm.models.AcmCurrent(*, exists: 'bool', certificate_arn: 'str | None', status: 'str | None', domain_name: 'str | None', validation_records: 'list[ValidationRecord]' = <factory>)[source]

Bases: object

certificate_arn: str | None
domain_name: str | None
exists: bool
status: str | None
validation_records: list[ValidationRecord]
class dxaws_acm.models.AcmDesired(*, domain_name: str, region: str | None = None, hosted_zone_id: str | None = None, zone_name: str | None = None, tags: dict[str, str]=<factory>)[source]

Bases: object

Desired ACM certificate state.

dxaws-acm issues one certificate per FQDN (no SAN bundles).

Hosted zone resolution and validation record management are delegated to dxaws-dns during apply.

zone_name and hosted_zone_id remain available as optional advanced hints/overrides, but normal callers should not need to provide them.

domain_name: str
hosted_zone_id: str | None
region: str | None
tags: dict[str, str]
zone_name: str | None
class dxaws_acm.models.AcmManagerResult(*, desired: 'AcmDesired', current: 'AcmCurrent', plan: 'AcmPlan', outputs: 'AcmOutputs | None', outcome: 'str')[source]

Bases: object

current: AcmCurrent
desired: AcmDesired
outcome: str
outputs: AcmOutputs | None
plan: AcmPlan
class dxaws_acm.models.AcmOutputs(*, certificate_arn: 'str', status: 'str')[source]

Bases: object

certificate_arn: str
status: str
class dxaws_acm.models.AcmPlan(*, desired: 'AcmDesired', current: 'AcmCurrent', action: 'PlanAction', certificate_arn: 'str | None' = None, dns_changes: 'list[dict[str, Any]]'=<factory>, wait: 'bool' = False, reason: 'str | None' = None, validation_records: 'list[ValidationRecord]' = <factory>)[source]

Bases: object

action: Literal['noop', 'request', 'ensure_dns', 'wait', 'recreate']
certificate_arn: str | None
current: AcmCurrent
desired: AcmDesired
dns_changes: list[dict[str, Any]]
property is_noop: bool
reason: str | None
validation_records: list[ValidationRecord]
wait: bool
class dxaws_acm.models.ApplyResult(result: Any)[source]

Bases: object

Represents the result of applying a plan.

Executors should return an ApplyResult capturing what actually occurred (created, updated, no-op, etc.).

result: Any
class dxaws_acm.models.DesiredState(spec: Any)[source]

Bases: object

Represents the desired state for this module.

Concrete modules should replace or extend this model with module-specific desired-state fields.

spec: Any
class dxaws_acm.models.Plan(plan: Any)[source]

Bases: object

Represents a plan to converge current state to desired state.

Planners should return a Plan instance describing what actions need to be taken. The structure of plan is module-defined.

plan: Any
class dxaws_acm.models.ValidationRecord(*, domain_name: 'str', name: 'str', type: 'str', value: 'str')[source]

Bases: object

domain_name: str
name: str
type: str
value: str

dxaws_acm.constants

dxaws_acm.constants.PKG_NAME = 'dxaws-acm'

Module-wide constants.

This file defines stable names and defaults that are shared across the module. Constants should be used for values that would otherwise become repeated string literals or “magic numbers” scattered through the codebase.

dxaws_acm.exceptions

Module-specific exceptions.

Keep exceptions stable once published. Callers may rely on these names for control flow and error handling.

exception dxaws_acm.exceptions.ApplyError[source]

Bases: DxAwsError

Raised when applying a plan fails.

exception dxaws_acm.exceptions.DxAwsError[source]

Bases: Exception

Base error for dxaws-acm.

exception dxaws_acm.exceptions.PlanError[source]

Bases: DxAwsError

Raised when planning fails (e.g., inconsistent current state or diffing failure).

exception dxaws_acm.exceptions.ProviderError[source]

Bases: DxAwsError

Raised when the provider encounters an unexpected or unrecoverable error.

exception dxaws_acm.exceptions.ValidationError[source]

Bases: DxAwsError

Raised when caller-provided desired state or arguments are invalid.

dxaws_acm.providers.base

class dxaws_acm.providers.base.ProviderBase(*args, **kwargs)[source]

Bases: Protocol

Provider interface for dxaws-acm.

Keep this small and stable; manager/planner logic relies on it for tests.

delete_certificate(*, certificate_arn: str) → None[source]

Delete a certificate by ARN (used by acceptance cleanup).

describe_certificate(*, certificate_arn: str) → CertificateInfo[source]
get_dns_validation_records(*, certificate_arn: str) → list[ValidationRecord][source]

Return validation records for a certificate ARN.

list_certificates(*, statuses: list[str] | None = None, include_status: bool = False) → list[CertificateSummary][source]
request_dns_validated_certificate(*, primary_domain: str, sans: list[str], tags: dict[str, str]) → str[source]

dxaws_acm.providers.aws

class dxaws_acm.providers.aws.AwsProvider(*, aws: AwsSession)[source]

Bases: AwsProviderBase

ACM provider.

All boto3 and AWS-specific behavior lives in this class. Planner/executor code must not import boto3 directly.

aws: AwsSession
delete_certificate(*, certificate_arn: str) → None[source]
describe_certificate(*, certificate_arn: str) → CertificateInfo[source]

Describe an ACM certificate and return normalized info.

get_dns_validation_records(*, certificate_arn: str) → list[ValidationRecord][source]
list_certificates(*, statuses: list[str] | None = None, include_status: bool = False) → list[CertificateSummary][source]

List certificate summaries (normalized).

Notes:

  • ACM list operations do not return Status. When include_status=True this method describes each certificate to populate status.

provider_ns: str
request_dns_validated_certificate(*, primary_domain: str, sans: list[str], tags: dict[str, str]) → str[source]

Request a DNS-validated certificate and return its ARN.

ACM IdempotencyToken constraints:

  • max length 32

  • must match w+ (no hyphens)

class dxaws_acm.providers.aws.CertificateInfo(*, certificate_arn: str, status: str, domain_name: str, domains: list[str], validation_records: list[ValidationRecord], failure_reason: str | None)[source]

Bases: object

Normalized certificate information returned by describe operations.

This is intentionally not a boto3 shape.

certificate_arn: str
domain_name: str
domains: list[str]
failure_reason: str | None
status: str
validation_records: list[ValidationRecord]
class dxaws_acm.providers.aws.CertificateSummary(*, certificate_arn: str, domain_name: str, status: str)[source]

Bases: object

Normalized certificate summary returned by list operations.

This is intentionally not a boto3 shape.

Note: - status may be empty when returned from list operations unless status enrichment is requested.

certificate_arn: str
domain_name: str
status: str
class dxaws_acm.providers.aws.ValidationRecord(*, domain_name: str, name: str, type: str, value: str)[source]

Bases: object

Normalized DNS validation record required by ACM.

Notes: - name is canonical FQDN with trailing dot. - value is canonical FQDN with trailing dot (ACM typically returns this already).

domain_name: str
name: str
type: str
value: str

dxaws_acm.providers.route53