airflow-api-client 0.1.0__py3-none-any.whl

airflow_api_client/__init__.py

@@ -0,0 +1 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0

airflow_api_client/auth.py

@@ -0,0 +1,164 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""Authentication provider for Airflow API client that supports JWT tokens.
+AirflowAPIClientAuthProvider is the default authentication provider for Airflow API client. Custom
+providers can be implemented by subclassing AirflowAPIClientAuthProvider and overriding the
+relevant methods. The provider can be configured via command-line arguments or environment
+variables.
+
+See --auth-provider argument in the CLI for more details on how to specify a custom authentication
+provider.
+"""
+
+import base64
+import json
+import os
+import time
+from abc import ABC, abstractmethod
+from argparse import ArgumentParser
+from typing import TYPE_CHECKING
+
+import requests
+
+from airflow_api_client.log import logger
+
+try:
+    import keyring  # noqa: F401, optional dependency for secure password storage
+except ImportError:
+    keyring = None
+
+if TYPE_CHECKING:
+    # The type hint for `args` argument
+    from configparser import RawConfigParser
+
+    from airflow_client.client import ApiClient
+
+
+class AuthToken(ABC):  # pylint: disable=too-few-public-methods
+    """Abstract base class for authentication tokens."""
+
+    @property
+    @abstractmethod
+    def expires(self) -> int:
+        """Returns the number of seconds until the token expires."""
+
+
+class AirflowClientJWTToken(AuthToken):  # pylint: disable=too-few-public-methods
+    """Represents a JWT token used for authenticating with the Airflow API."""
+
+    def __init__(self, token: str):
+        self.token = token
+
+        parts = token.split(".")
+        if len(parts) != 3:
+            raise ValueError("Invalid JWT format")
+
+        payload = parts[1]
+
+        # Add padding if needed (JWT uses base64url without padding)
+        padding = 4 - len(payload) % 4
+        if padding != 4:
+            payload += "=" * padding
+
+        # Decode base64
+        self.decoded = json.loads(base64.urlsafe_b64decode(payload))
+
+    @property
+    def expires(self) -> int:
+        # Returns the number of seconds until the token expires
+        return self.decoded.get("exp", 0) - int(time.time())
+
+
+class AirflowAPIClientAuthProvider:
+    """Default authentication provider for Airflow API client that supports username/password auth
+    and JWT tokens."""
+
+    def __init__(self, args):
+        self.args = args
+        self._token = None
+        self.timeout = 10
+
+    @property
+    def password(self) -> str:
+        """Returns the password for authentication. Falls back to keyring if available."""
+        if self.args.password is not None:
+            return self.args.password
+
+        if keyring:
+            password = keyring.get_password(
+                f"airflow-api-client/{self.args.endpoint}", self.username
+            )
+            if password:
+                logger.debug("Using password from keyring")
+                return password
+
+        raise ValueError(
+            "Password is required. Provide via --password, AIRFLOW_API_CLIENT_PASSWORD,"
+            " config file, or install keyring support: pip install airflow-api-client[keyring]"
+        )
+
+    @property
+    def username(self) -> str:
+        """Returns the username for authentication. Raises an error if username is not provided."""
+        if self.args.username is None:
+            raise ValueError("Username is required for DefaultAuthProvider")
+        return self.args.username
+
+    @property
+    def client_token(self) -> AirflowClientJWTToken:
+        """Returns a valid JWT token for authenticating with the Airflow API. If a valid token is
+        already cached, it returns the cached token. Otherwise, it fetches a new token using the
+        username and password."""
+        if self._token and self._token.expires > 60:
+            return self._token
+
+        env_token = os.getenv("AIRFLOW_API_CLIENT_TOKEN")
+        if env_token:
+            return AirflowClientJWTToken(env_token)
+
+        url = f"{self.args.endpoint}/auth/token"
+        response = requests.post(
+            url,
+            headers={"Content-Type": "application/json"},
+            json={
+                "username": self.username,
+                "password": self.password,
+            },
+            timeout=self.timeout,
+        )
+        logger.debug(f"Token response: {response.status_code} - {response.text}")
+        self._token = AirflowClientJWTToken(response.json()["access_token"])
+        return self._token
+
+    def set_client_configuration(self, client: "ApiClient") -> None:
+        """Configures the Airflow API client with the appropriate authentication headers. This
+        method is called by the CLI when initializing the API client.
+        `client` is the instance of airflow_client.client.ApiClient that needs to be configured with
+        authentication headers.
+        """
+        client.access_token = self.client_token.token
+
+    @classmethod
+    def add_arguments(cls, profile: str, parser: "ArgumentParser", config: "RawConfigParser"):
+        """Adds authentication-related command-line arguments to the parser. This method is called
+        by the CLI when setting up the argument parser for the specified profile. The arguments
+        added by this method will be available in the `args` object passed to the constructor of the
+        authentication provider.
+        """
+        parser.add_argument(
+            "--username",
+            "-u",
+            type=str,
+            default=os.getenv(
+                "AIRFLOW_API_CLIENT_USERNAME", config.get(profile, "username", fallback=None)
+            ),
+            help="Airflow username (typically your SSO)",
+        )
+        parser.add_argument(
+            "--password",
+            "-p",
+            type=str,
+            default=os.getenv(
+                "AIRFLOW_API_CLIENT_PASSWORD", config.get(profile, "password", fallback=None)
+            ),
+            help="Airflow password (if omitted, attempt to fetch from PWSafe",
+        )

airflow_api_client/commands/__init__.py

@@ -0,0 +1,36 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""Base class for CLI commands."""
+
+from abc import ABC, abstractmethod
+from argparse import ArgumentParser
+
+
+class Command(ABC):
+    """Base class for CLI commands."""
+
+    no_client = False
+
+    def __init__(self):
+        # The app is set by the CLI in main() before executing the command.
+        # This allows for commands that don't or can't require a client (eg. profile creation) to
+        # still be executed.
+        self.app = None
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Command name (e.g., 'xcom', 'run')."""
+
+    @property
+    @abstractmethod
+    def help(self) -> str:
+        """Help text for the command."""
+
+    @classmethod
+    @abstractmethod
+    def add_arguments(cls, parser: ArgumentParser):
+        """Add command-specific arguments to the subparser."""
+
+    @abstractmethod
+    def execute(self, **kwargs):
+        """Execute the command."""

airflow_api_client/commands/create_payload.py

@@ -0,0 +1,64 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""Command to construct a payload for a DAG run by prompting for values for each parameter defined
+in the DAG's parameters.
+"""
+
+import json
+
+from airflow_api_client.commands import Command
+from airflow_api_client.io import output
+from airflow_api_client.log import logger
+from airflow_api_client.models import DAG
+
+
+class CreatePayload(Command):
+    """Command to construct a payload for a DAG run by prompting for values for each parameter
+    defined in the DAG's parameters."""
+
+    name = "create-payload"
+    help = (
+        "Construct a payload for a DAG run by prompting for values for each parameter defined"
+        " in the DAG's parameters."
+    )
+
+    @classmethod
+    def add_arguments(cls, parser) -> None:
+        """Adds arguments for the command."""
+        parser.add_argument(
+            "dag_id",
+            metavar="DAG_ID",
+            help=(
+                "The ID of the DAG for which to create a payload. The DAG's parameters will be used"
+                " to prompt for values and construct the payload based on the DAGs `params`."
+            ),
+        )
+        parser.add_argument(
+            "--output-file",
+            "-o",
+            metavar="OUTPUT_FILE",
+            help=(
+                "Optional file path to save the constructed payload. If not provided, the payload"
+                " will be printed to the console."
+            ),
+        )
+
+    def execute(self, **kwargs) -> None:
+        """Returns the payload expected for a given DAG. Prompts for values for each parameter
+        defined in the DAG's parameters and constructs a payload dictionary.
+        """
+        logger.debug("Executing CreatePayload with arguments", dag_id=self.app.args.dag_id)
+        dag = DAG(self.app, self.app.args.dag_id)
+        parameters = dag.params or {}
+        payload = {}
+        logger.debug(
+            "Constructing payload for DAG run", dag_id=self.app.args.dag_id, parameters=parameters
+        )
+        payload = dag.create_payload()
+
+        if self.app.args.output_file:
+            with open(self.app.args.output_file, "w", encoding="utf-8") as f:
+                json.dump(payload, f, indent=4, sort_keys=True, default=str)
+            logger.info(f"Payload saved to {self.app.args.output_file}")
+        else:
+            output(json.dumps(payload, indent=4, sort_keys=True, default=str), self.app.args)
+        return payload

airflow_api_client/commands/get/__init__.py

@@ -0,0 +1,6 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""Get command module"""
+
+from airflow_api_client.commands.get.main import GetCommand
+
+__all__ = ["GetCommand"]

airflow_api_client/commands/get/dag.py

@@ -0,0 +1,23 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""Get DAG details"""
+
+from airflow_api_client.log import logger
+from airflow_api_client.models import DAG
+from airflow_api_client.typedefs import App
+
+
+class GetDagCommand:
+    """Helper class for getting DAG details"""
+
+    @classmethod
+    def add_subparser(cls, subparsers):
+        """Add subparser for dag"""
+        dag_parser = subparsers.add_parser("dag", help="Get DAG details")
+        dag_parser.add_argument("dag_id", help="DAG ID")
+
+    @staticmethod
+    def get_dag(app: App) -> dict:
+        """Get DAG details and return as dict"""
+        dag = DAG(app, app.args.dag_id)
+        logger.info(f"Retrieved details for DAG '{app.args.dag_id}'")
+        return dag.to_dict()

airflow_api_client/commands/get/dag_run.py

@@ -0,0 +1,27 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""Get DAG run details"""
+
+from airflow_api_client.log import logger
+from airflow_api_client.models import ResourceSpec
+from airflow_api_client.typedefs import App
+
+
+class GetDagRunCommand:
+    """Helper class for getting DAG run details"""
+
+    @classmethod
+    def add_subparser(cls, subparsers):
+        """Add subparser for dag-run"""
+        run_parser = subparsers.add_parser("dag-run", help="Get DAG run details")
+        run_parser.add_argument(
+            "spec",
+            metavar="DAG_ID/RUN_ID",
+            help="DAG run specification in format: DAG_ID/RUN_ID",
+        )
+
+    @staticmethod
+    def get_dag_run(app: App) -> dict:
+        """Get DAG run details and return as dict"""
+        spec = ResourceSpec.from_string(app, app.args.spec)
+        logger.info(f"Retrieved details for DAG run '{spec.dag_run.id}'")
+        return spec.dag_run.to_dict()

airflow_api_client/commands/get/log.py

@@ -0,0 +1,96 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""Get task instance log"""
+
+from airflow_client.client.exceptions import NotFoundException
+
+from airflow_api_client.io import output
+from airflow_api_client.log import logger
+from airflow_api_client.models import ResourceSpec
+from airflow_api_client.typedefs import App
+
+
+class GetLogCommand:
+    """Helper class for getting the log for a task instance"""
+
+    @classmethod
+    def add_subparser(cls, subparsers):
+        """Add subparser for task-instance"""
+        task_parser = subparsers.add_parser("log", help="Get task instance log")
+        task_parser.add_argument(
+            "spec",
+            metavar="DAG_ID/RUN_ID[/TASK_ID]",
+            help="Task instance specification in format: DAG_ID/RUN_ID/TASK_ID",
+        )
+        task_parser.add_argument(
+            "--try-number",
+            type=int,
+            default=1,
+            help="Try number of the task instance log to retrieve (default: 1)",
+        )
+
+        task_parser.add_argument(
+            "--time-format",
+            default="%Y-%m-%dT%H:%M:%S",
+            type=str,
+            help=(
+                "Time format for log timestamps (only applicable"
+                " for human output, default: '%%Y-%%m-%%dT%%H:%%M:%%S')."
+                " Supports strftime format codes. Only applies to human output, ignored for"
+                " JSON/YAML output."
+            ),
+        )
+
+    @staticmethod
+    def get_log(app: App) -> dict:
+        """Get task instance logs and return as dict"""
+        spec = ResourceSpec.from_string(app, app.args.spec)
+
+        task_instances = [spec.task_instance] if spec.task_instance else []
+        if not task_instances:
+            task_instances = spec.dag_run.task_instances
+
+        logger.debug(
+            f"Getting logs for task instances: {task_instances} in "
+            f" DAG: {spec.dag.id} and DAG Run: {spec.dag_run.id}"
+        )
+
+        if app.args.output_format == "human":
+            identifier = f"{spec.dag.id}/{spec.dag_run.id}"
+            for task_instance in task_instances:
+                if task_instance.try_number < app.args.try_number:
+                    logger.warning(
+                        f"Task instance {task_instance.id} has try number "
+                        f"{task_instance.try_number} which is less than the requested "
+                        f"try number {app.args.try_number}. Returning latest available log instead."
+                    )
+                output(
+                    [[f"Log for Task Instance: {identifier}/{task_instance.id}"]],
+                    app.args,
+                    headers=[],
+                )
+                try:
+                    task_instance.get_log(app.args.try_number).output(
+                        time_format=app.args.time_format
+                    )
+                except NotFoundException:
+                    logger.error(
+                        f"Failed to get log for task instance: {task_instance.id} (not found)"
+                        " Upstream failed or skipped?"
+                    )
+                    continue
+            return None
+
+        # json or yaml output
+        logs = {}
+        for task_instance in task_instances:
+            try:
+                log = task_instance.get_log(try_number=app.args.try_number)
+                logs[task_instance.id] = list(log)
+            except NotFoundException:
+                logger.error(
+                    f"Failed to get log for task instance: {task_instance.id} (not found)"
+                    " Upstream failed or skipped"
+                )
+                continue
+
+        return logs

airflow_api_client/commands/get/main.py

@@ -0,0 +1,72 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""Main get command with subcommand dispatch"""
+
+import json
+
+from airflow_api_client.commands import Command
+from airflow_api_client.commands.get.dag import GetDagCommand
+from airflow_api_client.commands.get.dag_run import GetDagRunCommand
+from airflow_api_client.commands.get.log import GetLogCommand
+from airflow_api_client.commands.get.task_instance import GetTaskInstanceCommand
+from airflow_api_client.io import output
+from airflow_api_client.log import logger
+
+DESCRIPTION = """
+Command to get details about a specific Airflow resource. This command retrieves full details
+about a DAG, DAG run, or task instance by its identifier. Unlike the list command which returns
+multiple resources, get returns a single resource with all available details.
+"""
+
+
+class GetCommand(Command):
+    """Command to get details about a specific resource."""
+
+    name = "get"
+    help = DESCRIPTION
+
+    @classmethod
+    def add_arguments(cls, parser) -> None:
+        subparsers = parser.add_subparsers(dest="resource_type", required=True)
+
+        GetDagCommand.add_subparser(subparsers)
+        GetDagRunCommand.add_subparser(subparsers)
+        GetTaskInstanceCommand.add_subparser(subparsers)
+        GetLogCommand.add_subparser(subparsers)
+
+    def execute(self, **kwargs) -> None:
+        """Get details about a specific resource"""
+        logger.debug(f"Executing GetCommand for resource type: {self.app.args.resource_type}")
+
+        result = None
+        if self.app.args.resource_type == "dag":
+
+            result = GetDagCommand.get_dag(self.app)
+        elif self.app.args.resource_type == "dag-run":
+
+            result = GetDagRunCommand.get_dag_run(self.app)
+        elif self.app.args.resource_type == "task-instance":
+
+            result = GetTaskInstanceCommand.get_task_instance(self.app)
+        elif self.app.args.resource_type == "log":
+            result = GetLogCommand.get_log(self.app)
+
+        if result:
+            # For human output, format as key-value table
+            if self.app.args.output_format == "human":
+                self._output_human(result)
+            else:
+                output(result, self.app.args)
+
+    def _output_human(self, data: dict) -> None:
+        """Output data in human-readable key-value format"""
+
+        rows = []
+        for key, value in sorted(data.items()):
+            # Format complex values as JSON
+            if isinstance(value, (dict, list)):
+                value_str = json.dumps(value, indent=2, default=str)
+            else:
+                value_str = str(value)
+            rows.append([key, value_str])
+
+        output(rows, self.app.args, headers=["Field", "Value"])

airflow_api_client/commands/get/task_instance.py

@@ -0,0 +1,32 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""Get task instance details"""
+
+from airflow_api_client.log import logger
+from airflow_api_client.models import ResourceSpec
+from airflow_api_client.typedefs import App
+
+
+class GetTaskInstanceCommand:
+    """Helper class for getting task instance details"""
+
+    @classmethod
+    def add_subparser(cls, subparsers):
+        """Add subparser for task-instance"""
+        task_parser = subparsers.add_parser("task-instance", help="Get task instance details")
+        task_parser.add_argument(
+            "spec",
+            metavar="DAG_ID/RUN_ID/TASK_ID",
+            help="Task instance specification in format: DAG_ID/RUN_ID/TASK_ID",
+        )
+
+    @staticmethod
+    def get_task_instance(app: App) -> dict:
+        """Get task instance details and return as dict"""
+        spec = ResourceSpec.from_string(app, app.args.spec)
+        if spec.task_instance is None:
+            raise ValueError(
+                f"Invalid task instance specification: {app.args.spec}. "
+                "Expected format: DAG_ID/RUN_ID/TASK_ID"
+            )
+        logger.info(f"Retrieved details for task instance '{spec.task_instance.task_id}'")
+        return spec.task_instance.to_dict()

airflow_api_client/commands/list/__init__.py

@@ -0,0 +1,6 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""List command module"""
+
+from airflow_api_client.commands.list.main import ListCommand
+
+__all__ = ["ListCommand"]

airflow_api_client/commands/list/base.py

@@ -0,0 +1,63 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""Base class for list commands"""
+
+from typing import Any, List
+
+from airflow_api_client.commands import Command
+from airflow_api_client.filters import get_obj_value
+from airflow_api_client.typedefs import App
+
+
+class ListCommandBase(Command):
+    """Base class for list commands with common functionality"""
+
+    @classmethod
+    def add_common_arguments(cls, parser) -> None:
+        """Add common arguments for all list commands"""
+        parser.add_argument(
+            "--filter",
+            "-f",
+            action="append",
+            help="""
+Filter results based on an object's value on the form: 'attr operator value', ie
+'is_paused == true' or 'owners !^ "airflow"'. Supported operators:
+" ==, !=, >, <, ^ (contains), !^ (not contains).  Repeat for multiple filters.
+Note that the value will be serialised using JSON, so use types accordingly. (eg. set `value` to
+`null` in order to match attributes with a value of `None` and enclose strings in
+quotation marks etc. Supports jmespath-notation to traverse objects.
+Note that this functionality is generic and can be used to filter on any
+attribute of any underlying object's JSON representation (see --output-format json) for obtaining
+the full JSON representation of each object to determine which attributes to filter on.
+See the airflow_client Python library docs for more info.
+            """,
+        )
+        parser.add_argument(
+            "--extra-attrs",
+            "-e",
+            type=str,
+            action="append",
+            help="""
+Extra attribute to include in the output.
+This will be included in the output alongside the default attributes for each resource. Output
+may be modified to better suit tabular representation. Repeat for multiple extra attributes.
+Related to notices in --filter. Richer objects such as lists and dictionaries are converted to
+comma-separated strings for better readability in table output, for more complex or verbatim
+output consider using the --output-format option with json or yaml and parsing the
+output with jq/yq or similar. Supports jmespath-notation to select attributes
+Example: list -e last_parse_duration -e owners -e default_args.has_on_failure_callback dags
+Or see slow DAG Runs: list -f "duration > 10" dag-runs my_dag_id
+                  """,
+        )
+
+    def _add_extra_attrs(self, app: App, obj: Any, headers: List, attrs: List) -> None:
+        """Helper method to add extra attributes to the output based on user input. Modifies headers
+        and attrs lists in place.
+        """
+        for extra_attr in app.args.extra_attrs or []:
+            extra_attr_value = get_obj_value(obj, extra_attr)
+            # Make lists and dicts more readable in output by converting to comma-separated strings
+            if hasattr(extra_attr_value, "__iter__") and not isinstance(extra_attr_value, str):
+                extra_attr_value = ", ".join(str(v) for v in extra_attr_value)
+
+            headers.append(extra_attr.replace("_", " ").replace(".", " ").title())
+            attrs.append(extra_attr_value)

airflow_api_client/commands/list/dag_runs.py

@@ -0,0 +1,62 @@
+# Copyright 2026 Rackspace Technology, Inc. SPDX-License-Identifier: Apache-2.0
+"""List DAG runs command"""
+
+from airflow_api_client.filters import filter_obj
+from airflow_api_client.io import output
+from airflow_api_client.models import DAG
+from airflow_api_client.typedefs import App
+
+
+class ListDagRunsCommand:
+    """Helper class for listing DAG runs"""
+
+    @classmethod
+    def add_subparser(cls, subparsers):
+        """Add subparser for dag-runs"""
+        runs_parser = subparsers.add_parser("dag-runs", help="List DAG runs")
+        runs_parser.add_argument("dag_id", help="DAG ID")
+        runs_parser.add_argument("--limit", type=int, default=10, help="Limit results")
+
+    @staticmethod
+    def list_dag_runs(app: App, add_extra_attrs_fn) -> None:
+        """List DAG runs for a given DAG"""
+
+        dag = DAG(app, app.args.dag_id)
+
+        dag_runs = dag.get_dag_runs(app.args.limit)
+
+        if app.args.filter:
+            dag_runs = [d for d in dag_runs if filter_obj(d, app.args.filter)]
+
+        if app.args.output_format in ("json", "yaml"):
+            output({"dag_runs": [d.to_dict() for d in dag_runs]}, app.args)
+        else:
+            headers = [
+                "DAG ID",
+                "Run ID",
+                "State",
+                "Run Type",
+                "Triggered Via",
+                "Triggered By",
+                "Duration",
+                "Start Date",
+                "End Date",
+            ]
+            data = []
+            for run in dag_runs:
+                attrs = [
+                    run.dag_id,
+                    run.id,
+                    run.state.value,
+                    run.run_type.value,
+                    run.triggered_by.value,
+                    run.triggering_user_name,
+                    run.duration,
+                    run.start_date,
+                    run.end_date,
+                ]
+
+                add_extra_attrs_fn(app, run, headers, attrs)
+
+                data.append(attrs)
+            output(data, app.args, headers=headers)