gh-117404: Soft deprecate zlib.ZLIB_RUNTIME_VERSION - #157816
StanFromIreland wants to merge 3 commits into
Conversation
Documentation build overview
10 files changed ·
|
|
Would not it be better to wait until we have |
|
This is just a soft deprecation, I'd like to deprecate it normally then, which is a few years down the line. |
| .. versionadded:: next | ||
|
|
||
|
|
||
| .. data:: ZLIB_RUNTIME_VERSION |
There was a problem hiding this comment.
Doesn't it look confusing that an alias is added earlier?
There was a problem hiding this comment.
Possibly, but I don't really foresee that being a particularly significant issue in practice. It's also not the first time this has happened, see re.match for example.
|
It’s an indication that you shouldn’t use it (since we’re planning to remove the alias in a few years). |
|
I am just a wrong person to ask for review, because I do not completely understand soft deprecation. |
|
I see, no worries. @hugovk, since I know you've soft-deprecated a few things before, do you think a soft-deprecation before a deprecation is reasonable? |
|
It's surprising that Python 3.16 adds |
|
Which is why I'm proposing a **soft-**deprecation, not a deprecation. |
|
The cost of having an old alias is very low, especially if it is a constant (we have aliases 20 or 30 years old). Soft deprecation disturbs documentation like normal deprecation. |
Soft deprecation is when we don't want people to use something (and ideally have a better alternative to suggest), and have no plans to remove it. Doing a regular deprecation before removal is a different thing. A soft deprecation doesn't graduate into a regular one. But if you are planning on removing something, don't hide it, do a regular deprecation. You can leave the removal open-ended, or pick some distant version and assess progress of removal closer to the time.
Agreed. Perhaps we could have the preferred name as the main docs entry and add something like "Prefer After that could open feature requests with Ruff's UP and pyupgrade to rewrite to the preferred name. |
|
If people prefer to keep the old alias, I won't fight this. Instead, I changed this to clearly note that the new name should be preferred. |
We already have this. |
Personally, it doesn't look that way to me. They are both listed together, and it's not clear why there are two APIs for the same information, and which one should be used. |
Use what you want. You can use newer API, you can find it more consistent, but we should not force you. |
I don't think a recommendation is forcing anyone, a deprecation would, but I'm not planning that currently. |
|
Too much documentation can make things looking more complex than they are. |
|
In my opinion, one sentence here does not hurt. |
4 participants
As it's now an alias to
zlib.zlib_version, I propose we soft deprecate the old API to encourage people to use the new one. It does still have a bit of use, so I'm not proposing we deprecate just yet.