Migrate Argument Clinic docs from CPython to the devguide #1151
Conversation
…"O!" format unit.
to improve readability.
'python' clinic block, not a 'clinic' clinic block. Patch written by Ryan Smith-Roberts.
Argument Clinic (see issue for details).
and return converter from existing functions.
* You may now specify an expression as the default value for a parameter! Example: "sys.maxsize - 1". This support is intentionally quite limited; you may only use values that can be represented as static C values. * Removed "doc_default", simplified support for "c_default" and "py_default". (I'm not sure we still even need "py_default", but I'm leaving it in for now in case a use presents itself.) * Parameter lines support a trailing '\\' as a line continuation character, allowing you to break up long lines. * The argument parsing code generated when supporting optional groups now uses PyTuple_GET_SIZE instead of PyTuple_GetSize, leading to a 850% speedup in parsing. (Just kidding, this is an unmeasurable difference.) * A bugfix for the recent regression where the generated prototype from pydoc for builtins would be littered with unreadable "=<object ...>"" default values for parameters that had no default value. * Converted some asserts into proper failure messages. * Many doc improvements and fixes.
delaying its output or even redirecting it to a separate file.
…__ and __init__ functions.
including correctly generating code for Clinic blocks inside C preprocessor conditional blocks.
"format units". Updated the documentation to match.
…le documentation typos. Related Issues: #issue21528 #issue24453
Back porting changeset db302b88fdb6 to 3.4 branch, which fixed multiple documentation typos. Related Issues: #issue21528 #issue24453
The underlying zlib library stores sizes in “unsigned int”. The corresponding Python parameters are all sizes of buffers filled in by zlib, so it is okay to reduce higher values to the UINT_MAX internal cap. OverflowError is still raised for sizes that do not fit in Py_ssize_t. Sizes are now limited to Py_ssize_t rather than unsigned long, because Python byte strings cannot be larger than Py_ssize_t. Previously this could result in a SystemError on 32-bit platforms. This resolves a regression in the gzip module when reading more than UINT_MAX or LONG_MAX bytes in one call, introduced by revision 62723172412c.
…dule Patch by Xiang Zhang.
Based on patch by Ville Skyttä.
…ting. Patch by Julien Palard.
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Previous ToC layout (excerpt):
- How to use symbolic default values
...
- How to assign default values to parameter
- How to use the ``NULL`` default value
- How to use expressions as default values
New layout:
- How to assign default values to parameter
- The ``NULL`` default value
- Symbolic default values
- Expressions as default values
… (#106904) Add Background as a toplevel section with the following subsections: - Background - The goals of Argument Clinic - Basic concepts and usage Rename "Converting your first function" to Tutorial. Add anchors for Background, Tutorial, and How-to Guides: - :ref:`clinic-background` - :ref:`clinic-tutorial` - :ref:`clinic-howtos` Link to these from within the Abstract. Break the compatibility paragraph out of Abstract and make it a note. Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
…07203) Instead, order the tutorial as one body of prose, making it easier to align the tutorial according to Diátaxis principles.
Split "Basic concepts and usage" into: - Reference - Terminology - CLI reference - Background - Basic concepts Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
…7508) Summarise the goals of Argument Clinic in a single sentence. Mention that Argument Clinic was introduced with PEP-436.
…7328) - Omit unneccesary wording and sentences - Don't mention implementation details (no digression, explanation) Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
…of parameters (#95151) It is now possible to deprecate passing parameters positionally with Argument Clinic, using the new '* [from X.Y]' syntax. (To be read as "keyword-only from Python version X.Y") Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
…7747) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
- fix formatting in @text_signature howto and NEWS entry - fix formatting and example text in deprecate-positionals howto
- use cpy-file iso. source - fix Sphinx complaint about 'range' - mark up abstract similar to other devguide pages
|
The following commit authors need to sign the Contributor License Agreement: Click the button to sign: |
There was a problem hiding this comment.
Should this documented be added to the table in https://devguide.python.org/#contributing too?
That sounds like a good idea. |
But, IMO, we should do that after the migration. I think it's better if this PR only focus on the act of migrating clinic.rst. |
There was a problem hiding this comment.
I think the git history is not be quite right here (due to d3b2f41 and 62ffd34) -- if you look in this branch's blame for clinic.rst, it only goes back to the "Add clinic.rst with history", rather than any earlier commits.
I believe that if you squash the two commits I linked above, git will properly detect it as a file moved operation & history will work. (This worked locally for me, at least!)
A
| @@ -110,6 +110,7 @@ def _asset_hash(path: os.PathLike[str]) -> str: | |||
| rediraffe_redirects = { | |||
| # Development Tools | |||
| "clang.rst": "development-tools/clang.rst", | |||
| "clinic.rst": "development-tools/clinic.rst", | |||
There was a problem hiding this comment.
These redirects were for when pages were at the top level -- it isn't really needeed for an entirely new page.
Thanks for the heads-up. I'll look into it. |
|
Closing in favour of #1160 |
Resolves #1148
📚 Documentation preview 📚: https://cpython-devguide--1151.org.readthedocs.build/