Describe Command Mechanism

The Describe Command Mechanism in the Meltano Airflow extension provides a structured way for the Meltano ecosystem to discover the capabilities, commands, and metadata of the extension. It acts as a self-documentation interface that identifies the available entry points—specifically the main extension commands and the passthrough invoker—allowing Meltano to integrate the extension as a utility within a project.

This mechanism is built upon the Meltano Extension Developer Kit (EDK), utilizing the ExtensionBase interface to provide standardized metadata. The output is typically consumed during plugin installation or discovery, helping define how Meltano interacts with the underlying Airflow CLI.
Sources: airflow_ext/main.py:65-79, airflow_ext/wrapper.py:115-127, README.md:16-25

Architecture and Core Components

The mechanism is implemented through a layered approach, starting from the CLI entry point defined in main.py and delegating the logic to the Airflow wrapper class.

Component Interaction

1. Typer CLI Application: Defines the @app.command() for describe, handling user input for output formatting.
2. Airflow Wrapper: Implements the describe() method which returns a models.Describe object containing the command definitions.
3. Meltano EDK: Provides the data models (Describe, ExtensionCommand, InvokerCommand) and the describe_formatted helper to handle serialization.

The flow shows how a request is routed from the CLI to the underlying EDK models to generate a formatted response.
Sources: airflow_ext/main.py:65-79, airflow_ext/wrapper.py:115-127

Command Definitions

The describe method explicitly defines two primary command sets that the extension supports. These are returned as a list of command models.

Available Commands Metadata

The airflow_extension entry point is used for extension-specific lifecycle management, while airflow_invoker allows users to run native Airflow commands (e.g., airflow version) through the extension wrapper.
Sources: airflow_ext/wrapper.py:121-125, pyproject.toml:34-35

Execution Logic

When the describe command is executed, the extension performs the following sequence:

1. Format Selection: The user provides an --format option (defaulting to DescribeFormat.text).
2. Metadata Retrieval: The Airflow.describe() method initializes a models.Describe object.
3. Serialization: The describe_formatted(output_format) method (inherited from ExtensionBase) converts the model into the requested string representation.
4. Error Handling: The CLI captures any uncaught exceptions during this process and logs them via structlog.

The sequence diagram illustrates the call stack from the initial CLI invocation to the base class formatting logic.
Sources: airflow_ext/main.py:65-79, airflow_ext/wrapper.py:115-127

Integration in meltano.yml

The output of the describe command informs the configuration required in a meltano.yml file. This allows Meltano to map specific utility commands to the extension's executables.

commands:
  describe:
    executable: airflow_extension
    args: describe
  initialize:
    executable: airflow_extension
    args: initialize
  invoke:
    executable: airflow_extension
    args: invoke

Sources: README.md:21-29

Implementation Details

The core logic is contained within the Airflow class in wrapper.py:

@override
def describe(self) -> models.Describe:
    """Describe the extension."""
    return models.Describe(
        commands=[
            models.ExtensionCommand(name="airflow_extension", description="airflow extension commands"),
            models.InvokerCommand(name="airflow_invoker", description="airflow pass through invoker"),
        ]
    )

Sources: airflow_ext/wrapper.py:115-127

The describe command in main.py exposes this functionality via Typer:

@app.command()
def describe(
    output_format: DescribeFormat = typer.Option(DescribeFormat.text, "--format", help="Output format"),
) -> None:
    try:
        typer.echo(ext.describe_formatted(output_format))
    except Exception:
        log.exception("describe failed with uncaught exception")
        sys.exit(1)

Sources: airflow_ext/main.py:65-79

Summary

The Describe Command Mechanism is a fundamental discovery protocol for the Meltano Airflow extension. By implementing the EDK's describe interface, the extension provides standardized metadata that identifies airflow_extension and airflow_invoker as the primary interaction points. This enables seamless integration within Meltano projects as a managed utility.