Support the new Deprecation HTTP header

The Deprecation header indicates that an API is deprecated, and shouldn't be used. It's either `true`, or an HTTP datetime value (the time after which the API is deprecated).

This is a draft HTTP standard from the IETF HTTPAPI working group: https://datatracker.ietf.org/doc/draft-ietf-httpapi-deprecation-header/. It's still a draft, but it's been around since 2019 and been through a few revisions already. It'd be great if it was supported by Requests!

I think there's a good argument that Requests should treat this like any of its own internal deprecation warnings (e.g. [a](https://github.com/psf/requests/blob/4f6c0187150af09d085c03096504934eb91c7a9e/requests/auth.py#L38-L55), [b](https://github.com/psf/requests/blob/589c4547338b592b1fb77c65663d8aa6fbb7e38b/requests/utils.py#L446-L450), [c](https://github.com/psf/requests/blob/589c4547338b592b1fb77c65663d8aa6fbb7e38b/requests/utils.py#L551-L555)), i.e. automatically logging it via `warnings` (if true, or if the date in the header has passed) to notify developers that they're depending on explicitly deprecated functionality. This seems like a quick standards-based win to help developers deal with API changes before their projects break, rather than later.

I understand if you'd prefer to wait until the standard is finalized, but in the meantime I'm just interested to know if the Requests team is open to supporting this in theory?

Feedback on the standard is also very welcome, the WG mailing list is here: https://www.ietf.org/mailman/listinfo/httpapi

Since this standard appears to not require any functional changes beyond unconditionally emitting warnings, should this instead be supported by applications that use Requests? That's my initial thought here. 

Yes, it could be, it's absolutely possible to handle application-side (with a session hook as the best option, I guess?)

I think there's a few reasons why this might be particularly valuable to have built-in though:

* There's a clear & useful default behaviour that Requests can very easily provide, which is in keeping with existing behaviour, and which would significantly ease painful API changes (by ensuring developers know about them before their code breaks).
* Deprecations are not rare events. 100% of APIs get deprecated and shutdown, eventually, so this is relevant to every application - it's not a niche feature.
* Having it as a built-in default is unusually valuable, because most of the time it's not clear that you need this when you're initially writing the code. When you first start sending requests to an API, it is presumably not deprecated.
* Supporting this drives a virtuous cycle for the HTTP ecosystem: having more popular HTTP clients warn users for you makes the standard immediately valuable to API developers, which drives adoption there, making more HTTP clients use it, etc, until deprecation notices for APIs become a solved problem everywhere (granted, this may take a while :smiley:).

Yeah, that's not this library's responsibility, nor should any HTTP focused library be raising exceptions for things like that breaking code unexpectedly and requiring significantly more work from users of the library to be aware of it to start and handle it explicitly.

Logging this via warnings (another option) is also a non-starter. We log (and warn) things that are legitimately more concerning and get heaping loads of complaints about that already. If we start warning this on a single request, I can't imagine the level of confusion and anger we'll receive. 

>     * Supporting this drives a virtuous cycle for the HTTP ecosystem: having more popular HTTP clients warn users for you makes the standard immediately valuable to API developers, which drives adoption there, making more HTTP clients use it, etc, until deprecation notices for APIs become a solved problem everywhere (granted, this may take a while smiley).

Alternatively, Requests supports this and other HTTP client developers see the vitriol that's poured out here and decide never to do that because developers tend to treat each other horribly, especially when the other is providing free labour.


> Yeah, that's not this library's responsibility, nor should any HTTP focused library be raising exceptions for things

Yep, absolutely not proposing anybody starts throwing exceptions for this - purely warning about it, to provide the same developer UX for API deprecations as any other deprecation.

> I can't imagine the level of confusion and anger we'll receive.

> developers tend to treat each other horribly, especially when the other is providing free labour.

Yeah, I sympathise, open-source users can be terrible people. I totally understand not wanting to merge things that'll increase your maintenance load or create angry users.

I have just found an interesting point though, which may help: I thought DeprecationWarnings were printed by default, but since Python 3.2 that's only true for code running in `__main__`, according to https://docs.python.org/3/library/warnings.html#default-warning-filter.

That means if Requests reported these as deprecations, they _wouldn't_ appear by default anywhere. They'd only show up for users who opt into deprecation warnings globally (for modern Python - we could just disable warning entirely for older Python versions).

That feels like a route that should avoid confusion & complaints, but would still be very valuable, since the users who explicitly want to hear about deprecations in general are exactly the users likely to also want to know if they're using deprecated APIs. That would mean a dev would just need to enable deprecation warnings globally to set this up, which is much easier than reconfiguring Requests everywhere they use it. I'd imagine that the warning would fire as a DeprecationWarning subclass (HttpDeprecationWarning, say), so users can also opt into deprecation warnings elsewhere but disable API warnings with standard warning filters, if they prefer.

Does that change the balance here at all?

Note that there's also a `Sunset` header, this one a published RFC: https://tools.ietf.org/html/rfc8594

I personally don't care if this is built into requests or a separate hook, though I would appreciate a convenient way to enable those warnings when I run with `python -Wd`.

There is indeed. They're intended to work together, and being worked on by overlapping groups in the IETF. Just to clarify the difference:

* The deprecation header signifies that the endpoint should no longer be used after a certain date (or if set to `true` just 'now'). I would expect that the date will normally be in the past.
* The sunset header signifies a date when the endpoint will completely stop working. It's normally a date in the future: if the date has passed, then you should assume the endpoint could disappear at any moment.

It's likely that you'd use them together: start serving deprecation headers when you're officially phasing out the endpoint, add a sunset header once you have a final shutdown date, and then shut it down on that shutdown date. There's some examples here: https://httptoolkit.tech/blog/how-to-turn-off-your-old-apis/. Debatable, but I think the former is the one that's most useful for warnings.

Since it is still beig a Draft...it is what it is.... 

There are a lot of forks  based on drafts that have been  dropped out before an official RFC was release, but.... any help is well received, so, if you have a solution in mind, please share it, and it could be added as API pre-release parameter, or something like...if the developer team agree with it...

remember this is a community effort team,so any help could be well received, but any support will be appreciated too...

Cheers


> There are a lot of forks based on drafts that have been dropped out before an official RFC was released

Yep, I think there's a very good argument for not implementing this today, or at least not enabling it by default, until the standard is finalized.

I posted this mainly to start a discussion _before_ that happens, to make it easier to implement this once/if this becomes a fully fledged IETF standard. Note that the sunset RFC is already a published RFC though ([RFC 8549](https://datatracker.ietf.org/doc/rfc8594/)).

Personally, I'd find it really useful if `python -Wd` automatically printed warnings when talking to deprecated and/or sunsetted HTTP APIs, since that's a strong sign that your code will stop working soon.

Going to close this as other maintainers have all agreed this is applications responsibility.