Implementation:Astronomer Astronomer cosmos Package Exports

Knowledge Sources	Astronomer_Astronomer_cosmos
Domains	Package Management, Lazy Loading, Airflow Operators
Last Updated	2026-02-07 17:00 GMT

Overview

Main package entry point for astronomer-cosmos that exports all public classes, operators, configs, and constants, with support for memory-optimised lazy imports controlled by a settings flag.

Description

The cosmos/__init__.py module serves as the top-level namespace for the astronomer-cosmos library (version 1.13.0). It conditionally loads all public symbols based on the settings.enable_memory_optimised_imports flag.

When memory-optimised imports are disabled (the default), the module eagerly imports and re-exports the following categories of symbols:

Core DAG and Task Group builders:

DbtDag from cosmos.airflow.dag
DbtTaskGroup from cosmos.airflow.task_group

Configuration classes:

ProjectConfig, ProfileConfig, ExecutionConfig, RenderConfig from cosmos.config

Constants and enums:

ExecutionMode, LoadMode, TestBehavior, InvocationMode, TestIndirectSelection, SourceRenderingBehavior, DbtResourceType from cosmos.constants

Local execution operators:

DbtBuildLocalOperator, DbtCloneLocalOperator, DbtDepsLocalOperator (deprecated, to be removed in Cosmos 2.x), DbtLSLocalOperator, DbtRunLocalOperator, DbtRunOperationLocalOperator, DbtSeedLocalOperator, DbtSnapshotLocalOperator, DbtTestLocalOperator

Optional provider operators are wrapped in try/except blocks with MissingPackage placeholders. If the required extra dependency is not installed, attempting to use the operator raises a helpful error message rather than a raw ImportError. The optional provider groups are:

Docker operators (extra: docker)
Kubernetes operators (extra: kubernetes)
Azure Container Instance operators (extra: azure-container-instance)
AWS EKS operators (extra: aws_eks)
AWS ECS operators (extra: aws-ecs)
GCP Cloud Run Job operators (extra: gcp-cloud-run-job)

When memory-optimised imports are enabled, none of these imports are executed at module load time, significantly reducing memory usage for environments where only a subset of cosmos functionality is needed.

The module defines a comprehensive __all__ list of 70+ symbols that constitutes the public API surface.

Usage

Use this module as the primary import entry point for all cosmos functionality. Users should import directly from the cosmos namespace rather than reaching into submodules.

Code Reference

Source Location

Repository: Astronomer_Astronomer_cosmos
File: cosmos/__init__.py
Lines: 1-326

Signature

# cosmos/__init__.py

from __future__ import annotations
from cosmos import settings

__version__ = "1.13.0"

if not settings.enable_memory_optimised_imports:
    from cosmos.airflow.dag import DbtDag
    from cosmos.airflow.task_group import DbtTaskGroup
    from cosmos.config import (
        ExecutionConfig,
        ProfileConfig,
        ProjectConfig,
        RenderConfig,
    )
    from cosmos.constants import (
        DbtResourceType,
        ExecutionMode,
        InvocationMode,
        LoadMode,
        SourceRenderingBehavior,
        TestBehavior,
        TestIndirectSelection,
    )
    # ... local operators, optional provider operators ...

__all__ = [
    "ProjectConfig", "ProfileConfig", "ExecutionConfig", "RenderConfig",
    "DbtDag", "DbtTaskGroup",
    "ExecutionMode", "LoadMode", "TestBehavior", "InvocationMode",
    "TestIndirectSelection", "SourceRenderingBehavior", "DbtResourceType",
    # ... 60+ operator classes across execution modes ...
]

Import

from cosmos import DbtDag, DbtTaskGroup, ProjectConfig, ProfileConfig, ExecutionConfig, RenderConfig
from cosmos import ExecutionMode, LoadMode, TestBehavior, InvocationMode
from cosmos import DbtRunLocalOperator, DbtTestLocalOperator, DbtBuildLocalOperator

I/O Contract

Inputs

Name	Type	Required	Description
settings.enable_memory_optimised_imports	bool	Yes	Controls whether eager imports are performed at module load time. When True, imports are deferred to reduce memory usage.

Outputs

Name	Type	Description
__version__	str	The package version string, currently `"1.13.0"`
DbtDag	class	DAG builder that renders a dbt project as an Airflow DAG
DbtTaskGroup	class	Task group builder that renders a dbt project as an Airflow TaskGroup
ProjectConfig	class	Configuration for specifying dbt project location and settings
ProfileConfig	class	Configuration for dbt profile and target settings
ExecutionConfig	class	Configuration for dbt execution parameters
RenderConfig	class	Configuration for DAG/TaskGroup rendering behaviour
ExecutionMode	enum	Enum specifying how dbt commands are executed (local, docker, kubernetes, etc.)
LoadMode	enum	Enum specifying how the dbt project graph is loaded
TestBehavior	enum	Enum controlling how dbt tests are run relative to models
InvocationMode	enum	Enum for dbt invocation method (subprocess vs. dbt runner)
Dbt*Operator classes	class	Operator classes for each dbt command across all execution modes (Local, Docker, Kubernetes, Azure, AWS EKS, AWS ECS, GCP Cloud Run)
MissingPackage	class	Placeholder that raises a clear error when an optional provider is not installed

Usage Examples

Basic Example

from cosmos import DbtDag, ProjectConfig, ProfileConfig, RenderConfig, ExecutionConfig

jaffle_shop = DbtDag(
    project_config=ProjectConfig("/usr/local/airflow/dags/dbt/jaffle_shop"),
    profile_config=ProfileConfig(
        profile_name="jaffle_shop",
        target_name="dev",
    ),
    render_config=RenderConfig(load_method=LoadMode.DBT_LS),
    execution_config=ExecutionConfig(execution_mode=ExecutionMode.LOCAL),
    dag_id="jaffle_shop_dag",
    schedule_interval="@daily",
    start_date=datetime(2023, 1, 1),
)

Memory-Optimised Import Example

# In airflow_settings.yaml or environment variables, enable:
# AIRFLOW__COSMOS__ENABLE_MEMORY_OPTIMISED_IMPORTS=True
#
# Then import only what you need directly from submodules:
from cosmos.airflow.dag import DbtDag
from cosmos.config import ProjectConfig, ProfileConfig

Checking for Optional Provider Availability

from cosmos import DbtRunKubernetesOperator

# If astronomer-cosmos[kubernetes] is not installed, using this operator
# will raise an error like:
#   "cosmos.operators.kubernetes.DbtRunKubernetesOperator requires the
#    'kubernetes' extra to be installed."

Related Pages

cosmos.airflow.dag.DbtDag -- DAG builder exported from this module
cosmos.airflow.task_group.DbtTaskGroup -- TaskGroup builder exported from this module
cosmos.config -- Configuration classes exported from this module
cosmos.constants -- Constants and enums exported from this module
cosmos.operators.local -- Local operator classes exported from this module
cosmos.operators.lazy_load.MissingPackage -- Placeholder class for optional providers

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment