Type-annotate SkipMixin and BaseXCom

[uranusjr]

Extracted from #19825, these are required to make Mypy pass checking the two files.

[github-actions]

The PR most likely needs to run full matrix of tests because it modifies parts of the core of Airflow. However, committers might decide to merge it quickly and take the risk. If they don't merge it quickly - please rebase it to the latest main at your convenience, or amend the last commit of the PR, and push it with --force-with-lease.

[ashb]

Tests are failing with "Object of type bytes is not JSON serializable" on trying to send XCom over the API.

[ashb]

I think this might be causing docs to fail too, as it's somehow finding two places for all the methods on XCom.

(I'm guessing as to cause, doc build is failing though)

[uranusjr]

I think this is fine, the cause is actually the overloads:

WARNING: duplicate object description of airflow.models.xcom.BaseXCom.clear, other instance in _api/airflow/models/xcom/index, use :noindex: for one of them

File path: apache-airflow/_api/airflow/models/xcom/index.rst (215)

 210 |    .. classmethod:: clear(cls, execution_date: pendulum.DateTime, dag_id: str, task_id: str, session: Optional[Session] = None)
 211 | 
 212 | 
 213 | 
 214 |    
>215 |    .. classmethod:: clear(cls, execution_date: Optional = None, dag_id: Optional = None, task_id: Optional = None, *, run_id: Optional = None, session: Session)
 216 | 
 217 |       Clears all XCom data from the database for the task instance
 218 | 
 219 |       ``run_id`` and ``execution_date`` are mutually exclusive.

I think generated by sphinx-autoapi. I’d expect it to support this years old feature; it’s very disappoiting.

[uranusjr]

Well actually it does support it since last year, but we’re pinning an extremely old version.

[ashb]

Every so often I've tried upgrading sphinx-autoapi, but last n times I tried there was a bug that meant it didn't build docs on a more recent version :(

[uranusjr]

Why are we using autoapi in the first place? Do we have any non-Python APIs that can’t be documented with sphinx.ext.autodoc?

[potiuk]

I think this is question mostly to @mik-laj who knows more of the context. But I share the same sentiment and experience as @ashb - any time I tried I backtracked so far. And yea - we are using extremely old version.

[uranusjr]

Wow autoapi 1.0 is so fucking ancient even my workaround does not work.

[uranusjr]

I added a hack to allow manually telling AutoAPI to ignore any code construct if the docstring contains :sphinx-autoapi-skip:. This is probably the best thing we can do, short of fixing overloads entirely.

Note that I chose to document the desired interface that uses run_id, instead of the actual interface that accepts both run_id and execution_date, because, well, we don’t want people to use execution_date if possible 🙂

[ashb]

I have just rebased this PR after the fix on main.

[uranusjr]

Rebasing (again) to hopefully fix the last of test failures.

[ashb]

✅ 🎉