Skip to content

docs: clarify AssetAlias usage with detailed explanation and examples #52259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
nrnavaneet wants to merge 4 commits into from
Closed

docs: clarify AssetAlias usage with detailed explanation and examples #52259

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3af3ead
docs: update public interface doc to reflect airflow.sdk and AIP-72
nrnavaneet Jun 24, 2025
ff3d500
Merge branch 'main' into update-public-interface-docs
nrnavaneet Jun 24, 2025
0538d94
Update airflow-core/docs/public-airflow-interface.rst
nrnavaneet Jun 25, 2025
8aef705
Merge branch 'main' into improve-assetalias-docs
nrnavaneet Jun 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions airflow-core/docs/public-airflow-interface.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,21 @@ and for automating certain aspects of the Airflow workflow.
Using Airflow Public Interfaces
===============================

.. note::

As of **Airflow 3.0**, users should use the ``airflow.sdk`` namespace as the official **Public Interface**, as defined in `AIP-72 <https://cwiki.apache.org/confluence/display/AIRFLOW/AIP-72+Task+Execution+Interface+aka+Task+SDK>`_.
Copy link
Contributor

@eladkal eladkal Jul 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the motivation to mention AIP-72? Generally speaking AIP numbering is internal information of Airflow developers they are not so meaningful to users (we do mention them sometimes but mostly for future plans not as reference to completed work)

Copy link
Member

@kaxil kaxil Jul 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This entire file is also being reworked as part of #52297 by @sunank200

Copy link
Contributor

@eladkal eladkal Jul 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah cool
so if it suppress this PR lets close it?

Copy link
Member

@kaxil kaxil Jul 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yea


Direct interaction with internal modules or the metadata database is not possible.
For stable, production-safe integration, it is recommended to use:

- The official **REST API**
- The **Python Client SDK** (`airflow-client-python`)
- The new **Task SDK** (``airflow.sdk``)

Related docs:
- `Release Notes 3.0 <https://airflow.apache.org/docs/apache-airflow/stable/release_notes.html>`_
- `Task SDK Overview <https://airflow.apache.org/docs/apache-airflow/stable/concepts/taskflow.html>`_
Comment on lines +43 to +44
Copy link
Contributor

@eladkal eladkal Jul 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should be relative links rather than http ones. We use http only for external resources


The following are some examples of the public interface of Airflow:

* When you are writing your own operators or hooks. This is commonly done when no hook or operator exists for your use case, or when perhaps when one exists but you need to customize the behavior.
Expand Down