gh-148849: Deprecate http.cookies.BaseCookie.js_output()

[kishorhange111]

gh-148849: Deprecate http.cookies.BaseCookie.js_output()

I didn’t see anyone assigned to this issue, so I tried working on it. I’m new to open source contributions, so please let me know if anything should be done differently.

This deprecates BaseCookie.js_output() as discussed in the issue. The method seems to be unused and tied to older browser behavior that isn’t really relevant anymore.

I added a deprecation decorator to the method, updated the existing tests to expect a DeprecationWarning, and updated the docs along with a NEWS entry.

I ran test_http_cookies locally — all tests pass (33 tests, 1 skipped):

Ran 33 tests in 0.122s
OK (skipped=1)

I also checked that calling js_output() raises the warning while still returning the same result.

I left Morsel.js_output() unchanged since the issue only mentions BaseCookie.js_output(), but I can update that too if needed.

Would appreciate a review whenever you get a chance. Thanks!

Fixes gh-148849

---

📚 Documentation preview 📚: https://cpython-previews--148978.org.readthedocs.build/

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[bedevere-app]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[picnixz]

Please, do not update your branch if there is no need to. Please read https://devguide.python.org/getting-started/pull-request-lifecycle/ before doing future contributions.

[kishorhange111]

I have made the requested changes; please review again

[bedevere-app]

Thanks for making the requested changes!

@picnixz: please review the changes made to this pull request.

[kishorhange111]

Please let me know if there are any further suggestions or changes needed.

[kishorhange111]

I have made the requested changes; please review again

[bedevere-app]

Thanks for making the requested changes!

@picnixz: please review the changes made to this pull request.

[picnixz]

Nothing to do on your side! Don't update your branch since there won't be a need to, I'll just wait a few days before alpha closes to merge this.

cc @sethmlarson @serhiy-storchaka @encukou

[sethmlarson]

LGTM!

[serhiy-storchaka]

LGTM. 👍

[encukou]

Sorry for being late to the party, but, IMO Morsel.js_output should be deprecated as well -- it has exactly the same issues.
(and BaseCookie uses that, so the warning should only be emitted there.)

[kishorhange111]

Hey, quick question — should I include this change in the current PR, or would you prefer I open a separate PR specifically for the Morsel.js_output update?

[encukou]

I'd prefer here since they're so related.

[kishorhange111]

I have made the requested changes; please review again.

As suggested by @encukou, I’ve deprecated Morsel.js_output(). The implementation now routes through Morsel.js_output(), so the deprecation warning is emitted only once.

Note on stacklevel:
The current implementation uses warnings._deprecated(), which has a fixed stacklevel=3. As a result, when BaseCookie.js_output() calls Morsel.js_output(), the warning points to BaseCookie.js_output() rather than the user's code. This could be improved by switching to warnings.warn() with a configurable stacklevel.
I'm happy to adjust this if preferred .

[bedevere-app]

Thanks for making the requested changes!

@picnixz, @StanFromIreland, @serhiy-storchaka: please review the changes made to this pull request.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32507822 | 📁 Comparing a91d066 against main (db0ee44)

  🔍 Preview build  

40 files changed · ± 40 modified

± Modified

• contents.html
• download.html
• genindex-B.html
• genindex-C.html
• genindex-E.html
• genindex-F.html
• genindex-G.html
• genindex-H.html
• genindex-I.html
• genindex-N.html
• and 30 more...

[serhiy-storchaka]

To avoid multiple deprecation warnings from internal use, you can add private Morsel._js_output and use it in BaseCookie.js_output and Morsel.js_output after emitting a warning.

You can use self.assertEqual(cm.filename, __file__) to assert that the warning points to the correct calling place.

[kishorhange111]

@serhiy-storchaka Thank you so much for the suggestion!
I've added Morsel._js_output() as a protected method containing the actual logic, so both Morsel.js_output() and BaseCookie.js_output() can warn independently and then delegate to _js_output(). This cleanly avoids multiple warnings and also fixes the stacklevel issue. I've also added cm.filename == file assertions to verify that the warning correctly points to the user's call site.

[sethmlarson]

Thank you!