Allow customized gone_in sentence for deprecation messages

[maresb]

What's the problem this feature will solve?
The current pip._internal.utils.deprecation:deprecated function, in at least one case (#10128), leads to an awkward and confusing deprecation message. I would like to make the message more customizable so that awkward wording is reduced.

Describe the solution you'd like
See #10129 (comment). Namely, I would like to introduce a new kwarg gone_in_message with default value DEPRECATION_GONE_IN_MESSAGE = "pip {} will remove support for this functionality.". I would also like to be able to set gone_in_message="" to omit the automatic generation of such a message.

This would allow me to achieve my desired wording:

pip currently copies the source tree into a temporary directory before building it. pip 21.3 will build packages in-place within the original source tree ("in-tree build"). This new behavior can be tested with the --use-feature=in-tree-build flag. Future versions of pip will remove support for out-of-tree builds, and for this testing flag. You can find discussion regarding this at {link}.

Alternative Solutions
I have tried to reword things to work with the builtin message phrasing, but it forced me to use awkward sentences like "Regarding...". See #10129 for further discussion.

[maresb]

(I have prepared a commit in order to make a PR, but my current wifi is blocking port 22 so I can't push yet...)

[uranusjr]

FWIW you can push via HTTPS (port 443). I use this often when I need to use public wifi 🙂

[pradyunsg]

Part of the point of the whole deprecated function is to allow the author to avoid thinking about the specific wording -- so that it's standardised and we don't spend time on iterating that when doing deprecations.

My preference is that we update the default wording we use for gone_in, to something like "In pip {version}, this behaviour change will be enforced." or something broader like that, instead of making this configurable.

In other words, I'm a -1 on adding an argument for making this an argument and making this possible. I'm a +1 to changing this to help us avoid weird sentences in the future.

[pradyunsg]

From #10129 (comment):

Some part of me wants to change it to something like:

DEPRECATION: pip copied a local directory before performing a build. This behaviour will change to stop copying and performing a build "in-tree".
pip 21.3 will enforce this behaviour change. You can use --use-feature=in-tree-build to test the upcoming behaviour.
Discussion regarding this change is at {link}.

This would, however, be a two-fold change -- partly here and partly in the deprecated function.

[maresb]

What bothers me about #10165 (comment) is that we are suggesting a flag which is already planned for deprecation. But based on the consensus from #10129 (comment) it seems that my concern is misguided.

So @pradyunsg, is your idea that you would like to add a new optional "preview" sentence like the following?

You can temporarily use --use-feature={preview_flag} to test the upcoming behavior.

[pradyunsg]

So @pradyunsg, is your idea that you would like to add a new optional "preview" sentence like the following?

That + changing the "remove this functionality" language to "enforce this change" (specific wording is in the quoted comments).

[maresb]

Here is my suggested wording for #10129, sentence by sentence, in the proper order, and according to whether the behavior change is in the past or future. I will adjust #10167 accordingly. Please request any desired adjustments.

Reason sentence (future or past):

DEPRECATION: pip copied the source tree into a temporary directory before building it. This is changing so that packages are built in-place within the original source tree ("in-tree build").

Version sentence (future):

pip 21.3 will enforce this behavior change.

Version sentence (past):

This behavior change has been enforced since pip 21.3.

Preview sentence (future):

You can temporarily use the flag --use-feature=in-tree-build to test the upcoming behavior.

Preview sentence (past):
[empty]

Link sentence (future or past):

Discussion can be found at {link}.

[pradyunsg]

I don't think we need any "past" phrasing. Once the default changes, we don't need to tell the users about it -- they'll either notice the change and deal with it; or be unaffected by the change.

[pradyunsg]

The deprecated helper actually raises an exception, if you run it on a version that's equal or higher than gone_in.

[maresb]

I believe we need some sort of "past" phrasing in order to fix #10223. In any case, as you suggest, we should adjust the message (telling the users or not) based on whether the change is already implemented.

As you point out, the logic was already implemented for whether the message gets raised as a warning or an exception. Now #10167 adjusts the message in the appropriate way.

Now it is possible to do

deprecated(
    reason='pip copied the source tree into a temporary directory before building it. This is changing so that packages are built in-place within the original source tree ("in-tree build").',
    replacement=None,
    gone_in="21.3",
    feature_flag="in-tree-build",
    issue=7555,
)

When the change is upcoming (future), then the following warning occurs:

<stdin>:1: PipDeprecationWarning: DEPRECATION: pip copied the source tree into a temporary
directory before building it. This is changing so that packages are built in-place within
the original source tree ("in-tree build"). pip 21.3 will enforce this behavior change.
You can temporarily use the flag --use-feature=in-tree-build to test the upcoming behavior.
Discussion can be found at https://github.com/pypa/pip/issues/7555.

When the change has already taken place, the following exception occurs:

pip._internal.utils.deprecation.PipDeprecationWarning: DEPRECATION: pip copied the source
tree into a temporary directory before building it. This is changing so that packages are
built in-place within the original source tree ("in-tree build"). This behavior change has
been enforced since pip 21.3. Discussion can be found at
https://github.com/pypa/pip/issues/7555.