deepyaman opened a new pull request, #29061:
URL: https://github.com/apache/flink/pull/29061
## What is the purpose of the change
`Deprecated` in `flink-python/pyflink/util/api_stability_decorators.py`
emitted its `DeprecationWarning` from `__call__`, which the decorator syntax
invokes in order to *apply* the decorator. The warning therefore fired at
decoration time — that is, at import — and the decorated function/class was
returned unwrapped, so:
- importing `pyflink.table` emitted a `DeprecationWarning` for every
deprecated API it defines, whether or not the user touches them;
- actually calling a deprecated API emitted nothing;
- `stacklevel=2` pointed at the decoration site inside PyFlink's own
source, not at user code.
```
$ cd flink-python && python -W error::DeprecationWarning -c "import
pyflink.table"
File ".../pyflink/table/table_schema.py", line 28, in <module>
@Deprecated(since="2.1.0", detail="""
File ".../pyflink/util/api_stability_decorators.py", line 141, in __call__
warnings.warn(msg, category=DeprecationWarning, stacklevel=2)
DeprecationWarning: TableSchema has been deprecated since version 2.1.0. ...
```
FLINK-37365, which introduced these decorators, describes the intended
behaviour as warning "at runtime on their invocation", so this was an
oversight. PyFlink supports Python >= 3.9, so `warnings.deprecated` (PEP 702)
is not available; the fix is by hand, mirroring PEP 702's semantics where
reasonable.
## Brief change log
- *`Deprecated` applied to a function returns a `functools.wraps` wrapper
that warns when the function is called, with `stacklevel=2` so the warning is
attributed to the caller.*
- *`Deprecated` applied to a class returns the class itself and wraps
`__init__` on it, so `isinstance` checks and subclassing are unaffected. As in
PEP 702 only instantiating the deprecated class itself warns, which also avoids
warning twice when a deprecated class inherits the `__init__` of a deprecated
base class.*
- *`staticmethod`/`classmethod` objects are unwrapped, decorated and
re-packaged; properties, ABCs and `Enum` subclasses fall back to applying the
docstring directive alone rather than raising. Decorating any of these
previously failed, as did omitting the `detail` argument.*
- *The message format, the `DeprecationWarning` category, the
docstring/Sphinx directives and the `__stability_decorators` attribute read by
`PythonAPICompletenessTestCase` are unchanged; `Experimental`, `Internal`,
`Public` and `PublicEvolving` are untouched.*
- *`pyflink/util` was not among the modules `dev/integration_test.sh`
runs, so it is added there.*
## Verifying this change
This change added tests and can be verified as follows:
- *Added `pyflink/util/tests/test_api_stability_decorators.py`: no warning
at decoration; a regression test that imports `pyflink.table` in a fresh
interpreter and asserts no deprecation warning is emitted; warning on function
call and on class instantiation; the warning is attributed to the caller's file
and line; docstring directives still applied; `__stability_decorators` still
populated; `staticmethod`/`classmethod`/property/ABC/`Enum` cases; subclassing
and double-warning guards; the other four decorators still silent and still
returning their argument unchanged.*
- *Red-green verified: 18 of the 21 new tests fail against the unfixed
decorator, and all 21 pass with the fix, on Python 3.9 (the minimum supported)
and 3.11.*
- *Manually verified that `python -W error::DeprecationWarning -c "import
pyflink.table"` no longer raises, and that calling `Table.get_schema` warns
exactly once, pointing at the calling script.*
- *`flake8` and `mypy` as configured in `flink-python/tox.ini` are clean,
and the Sphinx docs build (`SPHINXOPTS="-a -W" make html`) still succeeds, with
`Deprecated since version 2.1.0` still rendered on the affected APIs.*
## Does this pull request potentially affect one of the following parts:
- Dependencies (does it add or upgrade a dependency): **no**
- The public API, i.e., is any changed class annotated with
`@Public(Evolving)`: **no**
- The serializers: **no**
- The runtime per-record code paths (performance sensitive): **no**
- Anything that affects deployment or recovery: JobManager (and its
components), Checkpointing, Kubernetes/Yarn, ZooKeeper: **no**
- The S3 file system connector: **no**
## Documentation
- Does this pull request introduce a new feature? **no**
- If yes, how is the feature documented? **not applicable**
---
##### Was generative AI tooling used to co-author this PR?
- [X] Yes (please specify the tool below)
Generated-by: Claude Code 2.1.252 (Claude Opus 5)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
