Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

gh-105373: Doc lists pending removals #106540

Merged
merged 1 commit into from
Jul 9, 2023
Merged

gh-105373: Doc lists pending removals #106540

merged 1 commit into from
Jul 9, 2023

Conversation

vstinner
Copy link
Member

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

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

vstinner commented Jul 8, 2023

@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
Copy link
Member

hugovk commented Jul 8, 2023

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:

image

@vstinner vstinner merged commit 1e12c8c into python:main Jul 9, 2023
15 checks passed
@vstinner vstinner deleted the doc_pending_removals branch July 9, 2023 15:26
@vstinner
Copy link
Member Author

vstinner commented Jul 9, 2023

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
hugovk reviewed Jul 11, 2023
View reviewed changes
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`.
Copy link
Member

Choose a reason for hiding this comment

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

Needs some more info.

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

Copy link
Member Author

Choose a reason for hiding this comment

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

I created PR #106675 to elaborate this entry.

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

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

Choose a reason for hiding this comment

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

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).

Copy link
Member Author

Choose a reason for hiding this comment

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

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

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", {})``.
Copy link
Member

Choose a reason for hiding this comment

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

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:

Copy link
Member Author

Choose a reason for hiding this comment

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

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
Copy link
Member Author

Follow-up: PR #106675.

@hugovk hugovk mentioned this pull request Jul 21, 2023
Closed
4 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@hugovk 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
@vstinner @hugovk @bedevere-bot