Test: Migrate Argument Clinic docs rewritten #1
Conversation
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
…"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.
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.
…oc (#95529) The converter was removed in 74b5e4ce80858ac5c7d03411cb8cce7e6865f181
Co-authored-by: C.A.M. Gerlach <[email protected]>
…erters (python/cpython#104390) Use the unused keyword param in the converter to explicitly mark an argument as unused: /*[clinic input] SomeBaseClass.stubmethod flag: bool(unused=True) [clinic start generated code]*/
…hon#106842) Co-authored-by: Ezio Melotti <[email protected]>
…hon#106872) 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
…python/cpython#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 <[email protected]>
Co-authored-by: Ezio Melotti <[email protected]> Co-authored-by: Serhiy Storchaka <[email protected]>
…thon/cpython#107203) Instead, order the tutorial as one body of prose, making it easier to align the tutorial according to Diátaxis principles.
…/cpython#106981) Split "Basic concepts and usage" into: - Reference - Terminology - CLI reference - Background - Basic concepts Co-authored-by: Adam Turner <[email protected]> Co-authored-by: Alex Waygood <[email protected]> Co-authored-by: Ezio Melotti <[email protected]>
…hon/cpython#107508) Summarise the goals of Argument Clinic in a single sentence. Mention that Argument Clinic was introduced with PEP-436.
…hon/cpython#107328) - Omit unneccesary wording and sentences - Don't mention implementation details (no digression, explanation) Co-authored-by: Ezio Melotti <[email protected]>
…of parameters (python/cpython#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 <[email protected]> Co-authored-by: Serhiy Storchaka <[email protected]>
…hon/cpython#107747) Co-authored-by: Alex Waygood <[email protected]>
…n#107770) Co-authored-by: Serhiy Storchaka <[email protected]>
- 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
Owner
Author
|
GitHub links rewritten to point to |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
20 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
📚 Documentation preview 📚: https://cpython-devguide--1.org.readthedocs.build/