FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

gh-105373: Doc lists pending removals by vstinner · Pull Request #106540 · python/cpython · GitHub

  1. python
  2. cpython

Repository navigation

gh-105373: Doc lists pending removals - #106540

Merged
vstinner merged 1 commit into
python:mainfrom
vstinner:doc_pending_removals
Jul 9, 2023
ConversationCommits (1)ChecksFiles changed
Merged

gh-105373: Doc lists pending removals#106540
vstinner merged 1 commit into
python:mainfrom
vstinner:doc_pending_removals

Conversation

vstinner commented Jul 8, 2023 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Member

bedevere-bot added awaiting core review docs Documentation in the Doc dir skip news labels Jul 8, 2023
bedevere-bot mentioned this pull request Jul 8, 2023
Closed
vstinner force-pushed the doc_pending_removals branch 2 times, most recently from 875060e to aa6735b Compare July 8, 2023 00:58
vstinner force-pushed the doc_pending_removals branch from aa6735b to a9316b0 Compare July 8, 2023 01:04

vstinner commented Jul 8, 2023

Copy link
Copy Markdown
Member Author

@hugovk, @CAM-Gerlach: Would you mind to review my documentation of this long list of deprecated features?

I'm not sure if all of them must be listed under "Pending Removal", since some of them are "incompatible changes" rather than "removals". But it seems like we have this habit in the previous What's New documents as well. So I continued the trend.

The phrasing is... minimal. Basically, I copied/pasted error messages from the code which emits DeprecationWarning. Example:

re: bad character in group name.

Maybe this entry should be elaborated... a little bit. Or removed. I'm not sure.

I had troubles with Sphinx syntax:

:func:`~!urllib.parse.splittype`

This fails with: WARNING: py:func reference target not found: !urllib.parse.splittype and the Docs job fails. But if I write:

:func:`!~urllib.parse.splittype`

I get a ~ in the rendered HTML! I gave up and used this syntax:

``splittype()``

I don't want to get a reference to this function... since it's not documented. And it should not be documented, since it's deprecated.

I also added "Pending Removals" under the C API Changes section in a previous commit.

hugovk commented Jul 8, 2023

Copy link
Copy Markdown
Member

Quick comment about Sphinx syntax, will come back to the rest:

``splittype()`` is fine, or you could use :func:`!splittype` - both will display as splittype() but with slightly different styling:

vstinner merged commit 1e12c8c into python:main Jul 9, 2023
vstinner deleted the doc_pending_removals branch July 9, 2023 15:26

vstinner commented Jul 9, 2023

Copy link
Copy Markdown
Member Author

I merged my PR to continue the work on the issue #105373. But please, don't hesitate to propose a PR to enhance this documentation, or leave post-merge comments on this PR.

hugovk reviewed Jul 11, 2023
View reviewed changes
Comment thread Doc/whatsnew/3.13.rst
* :mod:`typing`: :class:`~typing.ByteString`, deprecated since Python 3.9,
now causes a :exc:`DeprecationWarning` to be emitted when it is used.

* :class:`!urllib.parse.Quoter`.

hugovk Jul 11, 2023

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Needs some more info.

Was deprecated with "It was not intended to be a public API" in PR #25798 by Greg, issue #88168.

vstinner Jul 12, 2023

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

I created PR #106675 to elaborate this entry.

Comment thread Doc/whatsnew/3.13.rst
Pending Removal in Python 3.14
------------------------------

* :mod:`argparse`: The *type*, *choices*, and *metavar* parameters

hugovk Jul 11, 2023

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

I like the practice of putting the module name at the start, and listing them alphabetically, makes it easier to find something.

Let's also alphabetise the main "Deprecated" section. (We could add a hidden comment at the top of the sections saying to add new ones alphabetically - see top of whole file for a hidden .. Rules for maintenance: comment).

vstinner Jul 12, 2023

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Please go ahead if you want to make a similar change in other sections :-)

Comment thread Doc/whatsnew/3.13.rst
Comment on lines +281 to +299
* :class:`typing.NamedTuple`:

* The undocumented keyword argument syntax for creating NamedTuple classes
(``NT = NamedTuple("NT", x=int)``) is deprecated, and will be disallowed in
3.15. Use the class-based syntax or the functional syntax instead.

* When using the functional syntax to create a NamedTuple class, failing to
pass a value to the 'fields' parameter (``NT = NamedTuple("NT")``) is
deprecated. Passing ``None`` to the 'fields' parameter
(``NT = NamedTuple("NT", None)``) is also deprecated. Both will be
disallowed in Python 3.15. To create a NamedTuple class with 0 fields, use
``class NT(NamedTuple): pass`` or ``NT = NamedTuple("NT", [])``.

* :class:`typing.TypedDict`: When using the functional syntax to create a
TypedDict class, failing to pass a value to the 'fields' parameter (``TD =
TypedDict("TD")``) is deprecated. Passing ``None`` to the 'fields' parameter
(``TD = TypedDict("TD", None)``) is also deprecated. Both will be disallowed
in Python 3.15. To create a TypedDict class with 0 fields, use ``class
TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})``.

hugovk Jul 11, 2023

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Hmm, these two are listed in the main "Deprecated" section.

Should they be in both or just one?

Looking at older What's New pages, some (but not all) sections have intro texts saying they're were only for deprecations from earlier versions:

  • What’s New In Python 3.11
    • Deprecated
      • "This section lists Python APIs that have been deprecated in Python 3.11."
      • Pending Removal in Python 3.12
        • "The following Python APIs have been deprecated in earlier Python releases, and will be removed in Python 3.12."
  • What’s New In Python 3.12
    • Deprecated
      • [no intro text]
      • Pending Removal in Python 3.13
        • "The following modules and APIs have been deprecated in earlier Python releases, and will be removed in Python 3.13."
      • Pending Removal in Python 3.14
        • [no intro text]
      • Pending Removal in Future Versions
        • "The following APIs were deprecated in earlier Python versions and will be removed, although there is currently no date scheduled for their removal."

re:

vstinner Jul 12, 2023

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

I put the two items in both sections on purpose. We can just copy/paste the Pending Removal section in the future What's New In Python 3.14, and people reading Pending Removal don't have to read the Deprecation section.

vstinner commented Jul 12, 2023

Copy link
Copy Markdown
Member Author

Follow-up: PR #106675.

hugovk mentioned this pull request Jul 21, 2023
Closed
4 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

hugovk hugovk left review comments

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

Back | FazBrowse Home | New Git URL