dxaws-core

What is dxaws-core?

#

dxaws-core is the foundation layer of the dxaws ecosystem.

It contains the shared primitives, patterns, and AWS plumbing that all other dxaws modules build upon.

If a piece of functionality:

• is needed by more than one module, and
• represents a stable, cross-cutting concern

then it likely belongs in dxaws-core.

What dxaws-core is responsible for

#

dxaws-core intentionally owns boring but critical infrastructure concerns, including:

• AWS session and credential handling
• standardized AWS client creation
• idempotency and caller reference helpers
• shared provider base classes
• common exceptions and utilities
• testing stubs for AWS interactions

By centralizing these concerns, higher-level modules stay focused on intent rather than plumbing.

AWS provider base

#

One of the most important components in dxaws-core is the shared AWS provider base class.

Conceptually:

class AwsProviderBase:
    def __init__(self, *, aws: AwsSession, provider_ns: str) -> None:
        ...

    def client(self, service: str):
        ...

    def token(self, name: str) -> str:
        ...

This base class provides:

• consistent access to boto3 clients
• standardized idempotency tokens
• shared naming and scoping via provider_ns

Every dxaws module that talks to AWS inherits from this base.

Provider namespaces

#

Each AWS provider supplies a provider namespace when initializing AwsProviderBase.

Examples:

• dns.route53
• acm
• cloudfront

Namespaces serve several purposes:

• prevent token collisions across modules
• make AWS calls traceable and readable
• encode module identity into AWS interactions

Namespaces are owned by modules, not callers.

Sessions and credentials

#

dxaws-core centralizes AWS session handling so that:

• credential sourcing is consistent
• assume-role logic is implemented once
• region handling is explicit

Other modules do not create boto3 sessions directly.

They receive an AwsSession object from the outside world and pass it through to providers.

This keeps modules composable and testable.

Testing support

#

dxaws-core includes lightweight testing utilities, such as:

• stub AWS sessions
• stub paginators
• fake client responses

These allow higher-level modules to test behavior without importing boto3 or requiring credentials.

Core intentionally does not provide heavy mocking frameworks.

What does NOT belong in dxaws-core

#

Just as important as what belongs in dxaws-core is what does not belong there.

Avoid putting the following into core:

• service-specific logic (ACM, Route 53, CloudFront, etc.)
• orchestration or decision-making logic
• cross-account workflows
• resource-specific schemas or models

If something feels “useful everywhere,” pause and check whether it is truly foundational or just convenient.

Dependency direction

#

All dxaws modules may depend on dxaws-core.

dxaws-core depends on nothing else in dxaws.

This one-way dependency rule is non-negotiable and keeps the ecosystem acyclic and understandable.

Design philosophy

#

dxaws-core follows a few guiding principles:

• boring is good – predictability beats cleverness
• explicit is better than implicit – no hidden globals or side effects
• shared only when necessary – duplication is sometimes preferable
• testability first – AWS access should be easy to stub

Core evolves slowly and deliberately.

When to change dxaws-core

#

Changes to dxaws-core should be rare and intentional.

A good reason to change core is:

• repeated copy-paste across modules
• a proven pattern that has stabilized
• a cross-cutting concern with no natural home elsewhere

A bad reason is convenience or premature abstraction.

Summary

#

• dxaws-core is the foundation of dxaws
• it owns AWS plumbing and shared primitives
• higher-level modules depend on it, not the other way around
• keeping core small and boring keeps dxaws scalable

If dxaws has a center of gravity, this is it.