iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 727: Rewordings and clarifications (#3315)

This commit is contained in:
Sebastián Ramírez 2023-08-30 00:33:48 +02:00 committed by GitHub
parent c8e245dedc
commit fb2279258a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 12 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
pep-0727.rst
View File

@ -2,14 +2,14 @@ PEP: 727
Title: Documentation Metadata in Typing Title: Documentation Metadata in Typing
Author: Sebastián Ramírez <tiangolo@gmail.com> Author: Sebastián Ramírez <tiangolo@gmail.com>
Sponsor: Jelle Zijlstra <jelle.zijlstra@gmail.com> Sponsor: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Discussions-To: Discussions-To: https://discuss.python.org/t/pep-727-documentation-metadata-in-typing/32566
Status: Draft Status: Draft
Type: Standards Track Type: Standards Track
Topic: Typing Topic: Typing
Content-Type: text/x-rst Content-Type: text/x-rst
Created: 28-Aug-2023 Created: 28-Aug-2023
Python-Version: 3.13 Python-Version: 3.13
Post-History: Post-History: `30-Aug-2023 <https://discuss.python.org/t/pep-727-documentation-metadata-in-typing/32566>`__
Abstract Abstract
@ -45,11 +45,17 @@ the actual parameter. This means it's easy to refactor a function, remove a para
and forget to remove its docs. The same happens when adding a new parameter: it's easy and forget to remove its docs. The same happens when adding a new parameter: it's easy
to forget to add the docstring for it. to forget to add the docstring for it.
Editors can't check or ensure the consistency of the parameters and their docs. And because of this same duplication of information (the parameter name) editors and
other tools would need to have complex custom logic to check or ensure the
consistency of the parameters in the signature and in their docstring, or they
would simply not be able to support that.
It's not possible to programatically test these docstrings, for example to ensure Additionally, it would be difficult to robustly parse varying existing docstring
documentation consistency for the parameters across several similar functions, at conventions to programatically get the documentation for each individual parameter
least not without implementing a custom syntax parser. or variable at runtime. This would be useful, for example,
for testing the contents of each parameter's documentation, to ensure consistency
across several similar functions, or to extract and expose that same parameter
documentation in some other way (e.g. an API, a CLI, etc).
Some of these previous formats tried to account for the lack of type annotations Some of these previous formats tried to account for the lack of type annotations
in older Python versions by including typing information in the docstrings, in older Python versions by including typing information in the docstrings,