API Modules

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

dxaws_accounts.module

class dxaws_accounts.module.AccountsModule(*, aws: AwsSession | None = None, provider: ProviderBase | None = None)

Bases: object

Public module facade.

Implements the dxaws declarative convergence flow:

desired state -> plan -> apply

Callers construct Module with an AwsSession (or a provider directly), then call plan() to compute an idempotent plan, or apply() to execute it.

apply(*, desired: Any) → ModuleApplyResult

plan(*, desired: Any) → ModulePlanResult

dxaws_accounts.module.Module

alias of AccountsModule

class dxaws_accounts.module.ModuleApplyResult(result: 'Any')

Bases: object

result: Any

class dxaws_accounts.module.ModulePlanResult(plan: 'Any')

Bases: object

plan: Any

dxaws_accounts.planner

dxaws_accounts.planner.plan(*, provider: ProviderBase, desired: Any) → Any

Compute a plan to converge current state to desired state.

Planners are responsible for deciding what should change. They must not perform side effects.

Responsibilities: - read current state via the provider (read-only operations) - compare current state to desired state - produce a deterministic, explicit plan describing required actions

The returned plan should be: - stable (same inputs -> same plan) - inspectable (easy to log or debug) - consumable by the executor

This template implementation performs no diffing and returns the desired state directly as the plan.

dxaws_accounts.executor

dxaws_accounts.executor.apply(*, provider: ProviderBase, plan: Any) → Any

Apply a previously computed plan.

Executors are responsible for performing side effects only. They must not compute desired state or make planning decisions.

Responsibilities: - execute plan actions in a stable, predictable order - perform all external interactions via the provider - be idempotent where possible

This template implementation is a no-op and simply returns the plan. Real modules should replace this with concrete execution logic.

dxaws_accounts.models

class dxaws_accounts.models.AccountAlias(alias: str, account_id: str)

Bases: object

Human-friendly alias for an AWS account ID.

account_id: str

alias: str

class dxaws_accounts.models.AccountSelection(account_id: str, source: str)

Bases: object

Represents the resolved account selection used for command execution.

account_id: str

source: str

class dxaws_accounts.models.ApplyResult(result: Any)

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_accounts.models.AwsOrgAccount(id: str, name: str, email: str, status: str)

Bases: object

Represents an AWS account as returned by AWS Organizations.

email: str

id: str

name: str

status: str

class dxaws_accounts.models.DesiredState(spec: Any)

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_accounts.models.Plan(plan: Any)

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_accounts.models.SyncResult(added: list[AwsOrgAccount], updated: list[AwsOrgAccount], removed: list[str])

Bases: object

Result of syncing accounts from AWS Organizations into local state.

added: list[AwsOrgAccount]

removed: list[str]

updated: list[AwsOrgAccount]

dxaws_accounts.constants

dxaws_accounts.constants.PKG_NAME = 'dxaws-accounts'

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_accounts.exceptions

Module-specific exceptions.

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

exception dxaws_accounts.exceptions.ApplyError

Bases: DxAwsError

Raised when applying a plan fails.

exception dxaws_accounts.exceptions.DxAwsError

Bases: Exception

Base error for dxaws-accounts.

exception dxaws_accounts.exceptions.PlanError

Bases: DxAwsError

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

exception dxaws_accounts.exceptions.ProviderError

Bases: DxAwsError

Raised when the provider encounters an unexpected or unrecoverable error.

exception dxaws_accounts.exceptions.ValidationError

Bases: DxAwsError

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

dxaws_accounts.providers.base

class dxaws_accounts.providers.base.ProviderBase(*args, **kwargs)

Bases: Protocol

Provider interface for dxaws-accounts.

dxaws_accounts.providers.aws

class dxaws_accounts.providers.aws.AwsProvider(*, aws)

Bases: AwsProviderBase

AWS implementation for dxaws-accounts.

This provider is intentionally thin: it only knows how to talk to AWS Organizations and convert AWS responses into our internal models.

aws: AwsSession

describe_org_account(*, account_id: str) → AwsOrgAccount

Fetch a single account from AWS Organizations.

list_org_accounts() → list[AwsOrgAccount]

List all accounts visible via AWS Organizations.

list_org_accounts_dict() → list[dict[str, Any]]

Return org accounts as plain dicts (useful for logging/tests).

provider_ns: str